Fix dartdoc for InstanceMirror.delegate and ClosureMirror.

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;
 //
 // ...the getter is named 'myField' and the setter is named
 // 'myField='.  This allows us to assign unique names to getters and
 // setters for the purposes of member lookup.
 
 /**
  * Basic reflection in Dart,
- * with support for introspection and dynamic evaluation.
+ * with support for introspection and dynamic invocation.
  *
  * *Introspection* is that subset of reflection by which a running
  * program can examine its own structure. For example, a function
  * that prints out the names of all the members of an arbitrary object.
  *
- * *Dynamic evaluation* refers the ability to evaluate code that
+ * *Dynamic invocation* refers the ability to evaluate code that
  * has not been literally specified at compile time, such as calling a method
  * whose name is provided as an argument (because it is looked up
  * in a database, or provided interactively by the user).
  *
  * ## How to interpret this library's documentation
  *
  * As a rule, the names of Dart declarations are represented using
  * instances of class [Symbol]. Whenever the doc speaks of an object *s*
  * of class [Symbol] denoting a name, it means the string that
  * was used to construct *s*.
@@ skipping 463 matching lines @@
    * or
    * (b) the remote objects reflected by this mirror and
    * by [other] are identical.
    */
   bool operator == (other);
 
   /**
    * Perform [invocation] on [reflectee].
    * Equivalent to
    *
-   * this.invoke(invocation.memberName,
-   *             invocation.positionalArguments,
-   *             invocation.namedArguments);
+   *     if (invocation.isGetter) {
+   *        return this.getField(invocation.memberName).reflectee;
+   *     } else if (invocation.isSetter) {
+   *       return this.setField(invocation.memberName,
+   *                            invocation.positionArguments[0]).reflectee;
+   *     } else {
+   *       return this.invoke(invocation.memberName,
+   *                          invocation.positionalArguments,
+   *                          invocation.namedArguments).reflectee;
+   *     }
    */
   delegate(Invocation invocation);
 }
 
 /**
  * A [ClosureMirror] reflects a closure.
  *
- * A [ClosureMirror] provides access to its captured variables and
- * provides the ability to execute its reflectee.
+ * A [ClosureMirror] provides the ability to execute its reflectee and
+ * introspect its function.

[gbracha, 2015/06/09 00:27:41]

Sigh. What is the point of a closure mirror? We can invoke call on the object
anyway. Likewise, we should be able to get the class of the closure, find the
declaration of call and go from there for introspection.

[rmacnak, 2015/06/09 00:40:10]

closureMirror.function isn't the same as closureMirror.type.declarations[#call]
(just as block class compiledMethodAt: #value isn't the same as block method).

  */
 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.
@@ skipping 894 matching lines @@
   final override;
 
   /**
    * See the documentation for [MirrorsUsed.symbols], [MirrorsUsed.targets], 
    * [MirrorsUsed.metaTargets] and [MirrorsUsed.override] for documentation 
    * of the parameters.
    */
   const MirrorsUsed(
       {this.symbols, this.targets, this.metaTargets, this.override});
 }