Refine spec for TypedefMirror.value and for ClosureMirror.findInContext.

sdk/lib/mirrors/mirrors.dart

 // Copyright (c) 2012, 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 618 matching lines @@
    * a type that is serializable across isolates (currently [num],
    * [String], or [bool]).
    */
   Future<InstanceMirror> applyAsync(List positionalArguments,
                                     [Map<Symbol, dynamic> namedArguments]);
 
   /**
    * Looks up the value of a name in the scope of the closure. The
    * result is a mirror on that value.
    *
+   * If the reflectee is not an actual closure, returns null.

[ahe, 2013/10/22 12:47:18]

How can that happen?

[gbracha, 2013/10/22 23:40:29]

We generate a closure mirror for anything that either is a closure, a function
or emulates a function (i.e, has a call() method. Ideally, findInContext would
work for the last category, but that is future work I think. So for now, it just
answers null.

[rmacnak, 2013/10/22 23:50:18]

See also https://codereview.chromium.org/26777002/

+   * Otherwise:
+   *
    * Let *s* be the contents of the string used to construct the symbol [name].
    *
+   * If *s* is not an identifier or a library prefix followed by an identifier
+   * an ArgumentError is thrown.

[ahe, 2013/10/22 12:47:18]

Long term, I like this. What about operators?

Short-term, I would like something like this:

If *s* is not a an identifier (or an operator), an ArgumentError is thrown. If
*s* is a library prefix, an ArgumentError is thrown.

[gbracha, 2013/10/22 23:40:29]

Operators do not have a meaning as an expression.  That said, it turns out this
actually works (Michael was more consistent than the language is) and will
closurize the operator just like an ordinary instance method.

I suppose I should document that.
I figured. 

+   *
    * If the expression *s* occurs within the source code of the reflectee,
    * and if any such occurrence refers to a declaration outside the reflectee,
    * then let *v* be the result of evaluating the expression *s* at such
    * an occurrence.
    * If *s = this*, and the reflectee was defined within the instance scope of
    * an object *o*, then let *v* be *o*.
    *
    * The returned value is the result of invoking the method [reflect] on
    * *v*.
    */
@@ skipping 330 matching lines @@
    */
    bool operator == (other);
 }
 
 /**
  * A [TypedefMirror] represents a typedef in a Dart language program.
  */
 abstract class TypedefMirror implements ClassMirror {
   /**
    * The defining type for this typedef.
+   * If the the type referred to by the reflectee is a function type 
+   * *F*, the result will be [:FunctionTypeMirror:] reflecting *F*
+   * which is abstract and has an abstract method [:call:] whose 
+   * signature corresponds to *F*.
    *
-   * For instance [:void f(int):] is the value for [:typedef void f(int):].
+   * As an example:
+   * [:void f(int):] is the value for [:typedef void f(int):].
    */
   TypeMirror get value;
 }
 
 /**
  * A [MethodMirror] reflects a Dart language function, method,
  * constructor, getter, or setter.
  */
 abstract class MethodMirror implements DeclarationMirror {
   /**
@@ skipping 381 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});
 }