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

sdk/lib/mirrors/mirrors.dart

Index: sdk/lib/mirrors/mirrors.dart
===================================================================
--- sdk/lib/mirrors/mirrors.dart	(revision 29045)
+++ sdk/lib/mirrors/mirrors.dart	(working copy)
@@ -649,17 +649,30 @@
    * 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});
 }
@@ -1006,6 +1019,10 @@
 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):].
    */