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 28831)
+++ sdk/lib/mirrors/mirrors.dart	(working copy)
@@ -636,8 +636,14 @@
    * 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
@@ -988,8 +994,13 @@
 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;
 }