anchor.diff:   *       new Foo().foo(); // Prints "foo".
    *       new Foo().bar(); // Might print an arbitrary (mangled) name, "bar".
    *     }
  - */
  -// TODO(ahe): Remove ", override: '*'" when it isn't necessary anymore.
  + *
  + * 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 to specify symbols today is using a single
  -  // string. In some cases, a const list of classes might be convenient. Some
  +  // 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.
   
     /**
  
positive.code:    *
     * The following text is non-normative:
     *
     * Specifying this option turns off the following warnings emitted by
     * dart2js:
     *
     * * Using "MirrorSystem.getName" may result in larger output.
     * * Using "new #{name}" may result in larger output.
     *
     * Use symbols = "*" to turn off the warnings mentioned above.
     *
     * For example, if using [noSuchMethod] to interact with a database, extract
     * all the possible column names and include them in this list.  Similarly,
     * if using [noSuchMethod] to interact with another language (JavaScript, for
     * example) extract all the identifiers from API used and include them in
     * this list.
     */
    final symbols;
  
  
negative.code:    * The following text is non-normative:
     *
     * For now, there is no formal description of what a reflective target is.
     * 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 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;
  
  