anchor.diff:     * The following text is non-normative:
      *
      * For now, there is no formal description of what a reflective target is.
  -   * Informally, it is a list of things that are expected to have fully
  -   * functional mirrors.
  +   * Informally, a target is a library, a class, a method or a field.
  +   *
  +   * Dart2js currently supports the following formats to specify targets:
  +   *
  +   * * A constant [List] containing [String] constants representing (qualified)
  +   *   names of targets and Dart types.
  +   * * A single [String] constant whose value is a comma-separated list of
  +   *   (qualified) names.
  +   * * A single Dart type.
  +   *
  +   * A (qualified) name is resolved to a target as follows:
  +   *
  +   * 1. If the qualified name matches a library name, the matching library is
  +   *    the target.
  +   * 2. Else, find the longest prefix of the name such that the prefix ends
  +   *    just before a `.` and is a library name. 
  +   * 3. Use that library as current scope. If no matching prefix was found, use
  +   *    the current library, i.e., the library where the [MirrorsUsed] 
  +   *    annotation was placed.
  +   * 4. Split the remaining suffix (the entire name if no library name was
  +   *    found in step 3) into a list of [String] using `.` as a 
  +   *    separator.
  +   * 5. Select all targets in the current scope whose name matches a [String] 
  +   *    from the list.
  +   *
  +   * For example:
  +   *
  +   *     library my.library.one;
  +   *
  +   *     class A {
  +   *       var aField;
  +   *     }
  +   *
  +   *     library main;
  +   *
  +   *     @MirrorsUsed(targets: "my.library.one.A.aField")
  +   *     import "dart:mirrors";
  +   *
  +   * The [MirrorsUsed] annotation specifies `A` and `aField` from library 
  +   * `my.library.one` as targets. This will mark the class `A` as a reflective
  +   * target. The target specification for `aField` has no effect, as there is
  +   * no target in `my.library.one` with that name. 
  +   * 
  +   * Note that everything within a target also is available for reflection.
  +   * So, if a library is specified as target, all classes in that library
  +   * become targets for reflection. Likewise, if a class is a target, all
  +   * its methods and fields become targets for reflection. As a consequence,
  +   * `aField` in the above example is also a reflective target.
  +   *
      */
     final targets;
   
     /**
      * A list of classes that when used as metadata indicates a reflective
  -   * target.
  -   *
  -   * See [targets].
  +   * target. See also [targets].
  +   *
  +   * The following text is non-normative:
  +   *
  +   * The format for specifying the list of classes is the same as used for
  +   * specifying [targets]. However, as a library cannot be used as a metadata
  +   * annotation in Dart, adding a library to the list of [metaTargets] has no
  +   * effect. In particular, adding a library to [metaTargets] does not make
  +   * the library's classes valid metadata annotations to enable reflection.
  +   *
  +   * If an instance of a class specified in [metaTargets] is used as 
  +   * metadata annotation on a library, class, field or method, that library,
  +   * class, field or  method is added to the set of targets for reflection. 
  +   *
  +   * Example usage:
  +   *
  +   *     library example;
  +   *     @MirrorsUsed(metaTargets: "example.Reflectable")
  +   *     import "dart:mirrors";
  +   *
  +   *     class Reflectable {
  +   *       const Reflectable();
  +   *     }
  +   *
  +   *     class Foo {
  +   *       @Reflectable()
  +   *       reflectableMethod() { ... }
  +   *
  +   *       nonReflectableMethod() { ... }
  +   *     }
  +   *
  +   * In the above example. `reflectableMethod` is marked as reflectable by
  +   * using the `Reflectable` class, which in turn is specified in the 
  +   * [metaTargets] annotation.
  +   *
  +   * The method `nonReflectableMethod` lacks a metadata annotation and thus 
  +   * will not be reflectable at runtime.
      */
     final metaTargets;
   
  
positive.code:  *
   * Example usage:
   *
   *     @MirrorsUsed(symbols: 'foo', override: '*')
   *     import 'dart:mirrors';
   *
   *     class Foo {
  
negative.code:  *       new Foo().foo(); // Prints "foo".
   *       new Foo().bar(); // Might print an arbitrary (mangled) name, "bar".
   *     }
   *
   * For a detailed description of the parameters to the [MirrorsUsed] constructor
   * see the comments for [symbols], [targets], [metaTargets] and [override].
   *
   * An import of `dart:mirrors` may have multiple [MirrorsUsed] annotations. This
   * is particularly helpful to specify overrides for specific libraries. For 
   * example:
   *
   *     @MirrorsUsed(targets: 'foo.Bar', override: 'foo')
   *     @MirrorsUsed(targets: 'Bar')
   *     import 'dart:mirrors';
   *
   * will ensure that the target `Bar` from the current library and from library
   * `foo` is available for reflection. See also [override].
   */
  class MirrorsUsed {
    // Note: the fields of this class are untyped.  This is because the most
    // convenient way to specify symbols today is using a single string. In 
    // some cases, a const list of classes might be convenient. Some
    // might prefer to use a const list of symbols.
  
    /**
  