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 3275884443ae0058fc912cb2e1a17d166e943922..d16e62eecb7fc4e63e4518e7ffd4398b8c562fda 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 for
+   * each 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;
 
@@ -829,6 +839,8 @@ abstract class FunctionTypeMirror implements ClassMirror {
   /**
    * A mirror on the [:call:] method for the reflectee.
    */
+  // This is only here because in the past the VM did not implement a call
+  // method on closures.
   MethodMirror get callMethod;
 }