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 function, that is, a 
+   * user-defined 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.
+   *
+   * 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* denotes a prefix defined by an import-as clause in the surrounding 
+   * library an ArgumentError is thrown.
    * 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/24 13:29:43]

OK, now I understand this better, I'm concerned that findInContext is for
looking up values, not declarations. I had overlooked that previously.

I don't see dart2js being able to support this method in release 1.0.

I think we need to remove this method from the API for now.

+   * 
    * The returned value is the result of invoking the method [reflect] on
    * *v*.
+   * In any other case, *v* is unbound and this method returns null.
    */
   InstanceMirror findInContext(Symbol name, {ifAbsent: null});
 }
 
 /**
  * A [LibraryMirror] reflects a Dart language library, providing
  * access to the variables, functions, and classes of the
  * library.
  */
 abstract class LibraryMirror implements DeclarationMirror, ObjectMirror {
@@ skipping 326 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});
 }