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 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.

 
   /**
    * 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].
    * Then this method will perform the method invocation
    *  *f(a1, ..., an, k1: v1, ..., km: vm)*
@@ skipping 316 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.
    */
   MethodMirror get callMethod;

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

When might this be different than declarations[#call] ?

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

It wouldn't be but it's here.

 }
 
 /**
  * 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 371 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});
 }