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 631 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/23 17:58:59]

I think "actual closure" could be made a little more precise somehow. I'm not
sure if we the terminology already.

As far as I can tell, the language specification uses the terminology "function"
to describe what you call "actual closure". I'm sure implicit/tear-off closures
complicate this picture.

So how about:

If the reflectee is not an actual function, that is, a declared class which
implements [Function], this method returns null.

+   * Otherwise:
+   *
    * Let *s* be the contents of the string used to construct the symbol [name].
    *
-   * If the expression *s* occurs within the source code of the reflectee,
+   * If *s* is not an identifier or the name of an operator 
+   * an ArgumentError is thrown.

[ahe, 2013/10/23 17:58:59]

Short-term, also throw an argument error if s is a prefix.

+   *
+   * If *s* is an identifier and 
+   * 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*.
+   * If *s* is the name of an operator, let *v* be (x) => this s x.

[ahe, 2013/10/23 17:58:59]

I don't understand this part.

    *
    * The returned value is the result of invoking the method [reflect] on
    * *v*.
    */
   InstanceMirror findInContext(Symbol name, {ifAbsent: null});
 }
 
 /**
  * A [LibraryMirror] reflects a Dart language library, providing
  * access to the variables, functions, and classes of the
@@ skipping 329 matching lines @@
    */
    bool operator == (other);
 }
 
 /**
  * A [TypedefMirror] represents a typedef in a Dart language program.
  */
 abstract class TypedefMirror implements TypeMirror {
   /**
    * 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 referent for [:typedef void f(int):].
    */
   TypeMirror get referent;
 }
 
 /**
  * A [MethodMirror] reflects a Dart language function, method,
  * constructor, getter, or setter.
  */
@@ skipping 383 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});
 }