Improve doc for ClosureMirror.function.

sdk/lib/mirrors/mirrors.dart

Index: sdk/lib/mirrors/mirrors.dart
diff --git a/sdk/lib/mirrors/mirrors.dart b/sdk/lib/mirrors/mirrors.dart
index 7fb810e9b87d3ff865768437e9ce35f6ba18f0f5..24654fce3a36764a8bb3bce0ecfbe3fe251d17da 100644
--- a/sdk/lib/mirrors/mirrors.dart
+++ b/sdk/lib/mirrors/mirrors.dart
@@ -496,6 +496,16 @@ abstract class ClosureMirror implements InstanceMirror {
    *
    * The function associated with an instance of a class that has a [:call:]
    * method is that [:call:] method.
+   *
+   * A Dart implementation might choose to create a class for each closure
+   * expression, in which case [:function:] would be the same as
+   * [:type.declarations[#call]:]. But the Dart language model does not require
+   * this. A more typical implementation involves a single closure class or a
+   * closure class for each arity or type signature, where the call method
+   * dispatches to a function held in the closure rather the call method
+   * directly implementing the closure body. So one cannot rely on closures from
+   * distinct closure expressions having distinct classes ([:type:]), but one
+   * can rely on them having distinct functions ([:function:]).
    */
   MethodMirror get function;

[rmacnak, 2014/05/06 20:12:21]

Actually, the accessors on FunctionTypeMirror would seem to imply there must be
a distinct closure class for each signature.

[gbracha, 2014/09/11 00:49:33]

I don't think so today. Just as function could return a different value from a
common class (by storing it in a field), the same would be true of the type
accessors.

I think it might be nice to explain this subtlety in the comment as well.