Improve doc for ClosureMirror.function.

sdk/lib/mirrors/mirrors.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 // For the purposes of the mirrors library, we adopt a naming
 // convention with respect to getters and setters.  Specifically, for
 // some variable or field...
 //
 //   var myField;
 //
@@ skipping 478 matching lines @@
  */
 abstract class ClosureMirror implements InstanceMirror {
   /**
    * A mirror on the function associated with this closure.
    *
    * The function associated with an implicit closure of a function is that
    * function.
    *
    * 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;
 
   /**
    * Executes the closure and returns a mirror on the result.
    * Let *f* be the closure reflected by this mirror,
    * let *a1, ..., an* be the elements of [positionalArguments]
    * let *k1, ..., km* be the identifiers denoted by the elements of
    * [namedArguments.keys]
    * and let *v1, ..., vm* be the elements of [namedArguments.values].
@@ skipping 313 matching lines @@
   TypeMirror get returnType;
 
   /**
    * Returns a list of the parameter types of the reflectee.
    */
   List<ParameterMirror> get parameters;
 
   /**
    * 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;
 }
 
 /**
  * A [TypeVariableMirror] represents a type parameter of a generic
  * type.
  */
 abstract class TypeVariableMirror extends TypeMirror {
   /**
    * A mirror on the type that is the upper bound of this type variable.
@@ skipping 372 matching lines @@
    *
    * When used as metadata on an import of "dart:mirrors", this metadata does
    * not apply to the library in which the annotation is used, but instead
    * applies to the other libraries (all libraries if "*" is used).
    */
   final override;
 
   const MirrorsUsed(
       {this.symbols, this.targets, this.metaTargets, this.override});
 }