Format doc comments in mirrors, lines 480 through 1160

sdk/lib/mirrors/mirrors.dart

 // Copyright (c) 2013, 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 462 matching lines @@
    * A mirror on the type of the reflectee.
    *
    * Returns a mirror on the actual class of the reflectee.
    * The class of the reflectee may differ from
    * the object returned by invoking [runtimeType] on
    * the reflectee.
    */
   ClassMirror get type;
 
   /**
-   * Does [reflectee] contain the instance reflected by this mirror?
-   * This will always be true in the local case (reflecting instances
-   * in the same isolate), but only true in the remote case if this
-   * mirror reflects a simple value.
+   * Whether [reflectee] will return the instance reflected by this mirror.
+   *
+   * This will always be true in the local case (reflecting instances in the
+   * same isolate), but only true in the remote case if this mirror reflects a
+   * simple value.
    *
    * A value is simple if one of the following holds:
-   *  - the value is [:null:]
-   *  - the value is of type [num]
-   *  - the value is of type [bool]
-   *  - the value is of type [String]
+   *
+   * * the value is [:null:]
+   * * the value is of type [num]
+   * * the value is of type [bool]
+   * * the value is of type [String]
    */
   bool get hasReflectee;
 
   /**
    * If the [InstanceMirror] reflects an instance it is meaningful to
    * have a local reference to, we provide access to the actual
    * instance here.
    *
    * If you access [reflectee] when [hasReflectee] is false, an
    * exception is thrown.
    */
   get reflectee;
 
   /**
-   * Returns true if this mirror is equal to [other].
+   * Whether this mirror is equal to [other].
+   *
    * The equality holds if and only if
-   * (1) [other] is a mirror of the same kind
-   * and
-   * (2) either
-   * (a) [hasReflectee] is true and so is
-   * [:identical(reflectee, other.reflectee):]
-   * or
-   * (b) the remote objects reflected by this mirror and
-   * by [other] are identical.
+   *
+   * 1. [other] is a mirror of the same kind, and
+   * 2. either
+   *
+   *    a. [hasReflectee] is true and so is
+   *    [:identical(reflectee, other.reflectee):], or
+   *
+   *    b. the remote objects reflected by this mirror and by [other] are
+   *    identical.
    */
   bool operator == (other);
 }
 
 /**
  * A [ClosureMirror] reflects a closure.
  *
  * A [ClosureMirror] provides the ability to execute its reflectee and
  * introspect its function.
  */
@@ skipping 14 matching lines @@
    * each type signature, where the call method dispatches to a function held
    * in the closure rather the call method
    * directly implementing the closure body. So one cannot rely on closures from
    * distinct closure expressions having distinct classes ([:type:]), but one
    * can rely on them having distinct functions ([:function:]).
    */
   MethodMirror get function;
 
   /**
    * Executes the closure and returns a mirror on the result.
+   *
    * Let *f* be the closure reflected by this mirror,
-   * let *a1, ..., an* be the elements of [positionalArguments]
+   * let *a1, ..., an* be the elements of [positionalArguments],
    * let *k1, ..., km* be the identifiers denoted by the elements of
-   * [namedArguments.keys]
+   * [namedArguments.keys],
    * and let *v1, ..., vm* be the elements of [namedArguments.values].
+   *
    * Then this method will perform the method invocation
-   *  *f(a1, ..., an, k1: v1, ..., km: vm)*
-   * If the invocation returns a result *r*, this method returns
-   * the result of calling [reflect]\(*r*\).
-   * If the invocation causes a compilation error
-   * the effect is the same as if a non-reflective compilation error
-   * had been encountered.
-   * If the invocation throws an exception *e* (that it does not catch)
-   * this method throws *e*.
+   * *f(a1, ..., an, k1: v1, ..., km: vm)*.
+   *
+   * If the invocation returns a result *r*, this method returns the result of
+   * calling [reflect]\(*r*\).
+   *
+   * If the invocation causes a compilation error, the effect is the same as if
+   * a non-reflective compilation error had been encountered.
+   *
+   * If the invocation throws an exception *e* (that it does not catch), this
+   * method throws *e*.
    */
   InstanceMirror apply(List positionalArguments,
                        [Map<Symbol, dynamic> namedArguments]);
 }
 
 /**
  * A [LibraryMirror] reflects a Dart language library, providing
  * access to the variables, functions, and classes of the
  * library.
  */
 abstract class LibraryMirror implements DeclarationMirror, ObjectMirror {
   /**
    * The absolute uri of the library.
    */
   Uri get uri;
 
   /**
    * Returns an immutable map of the declarations actually given in the library.
    *
    * This map includes all regular methods, getters, setters, fields, classes
    * and typedefs actually declared in the library. The map is keyed by the
    * simple names of the declarations.
    */
   Map<Symbol, DeclarationMirror> get declarations;
 
   /**
-   * Returns [:true:] if this mirror is equal to [other].
-   * Otherwise returns [:false:].
+   * Whether this mirror is equal to [other].
    *
    * The equality holds if and only if
-   * (1) [other] is a mirror of the same kind
-   * and
-   * (2)  The library being reflected by this mirror
-   * and the library being reflected by [other]
-   * are
-   * the same library in the same isolate.
+   *
+   * 1. [other] is a mirror of the same kind, and
+   * 2. The library being reflected by this mirror and the library being
+   *    reflected by [other] are the same library in the same isolate.
    */
-   bool operator ==(other);
+  bool operator ==(other);
 
   /**
    * Returns a list of the imports and exports in this library;
    */
   List<LibraryDependencyMirror> get libraryDependencies;
 }
 
 /// A mirror on an import or export declaration.
 abstract class LibraryDependencyMirror implements Mirror {
   /// Is `true` if this dependency is an import.
@@ skipping 106 matching lines @@
    * For most classes, they are their own original declaration.  For
    * generic classes, however, there is a distinction between the
    * original class declaration, which has unbound type variables, and
    * the instantiations of generic classes, which have bound type
    * variables.
    */
   TypeMirror get originalDeclaration;
 
 
   /**
-   * Checks the subtype relationship, denoted by [:<::] in the language
-   * specification. This is the type relationship used in [:is:] test checks.
+   * Checks the subtype relationship, denoted by `<:` in the language
+   * specification.
+   *
+   * This is the type relationship used in `is` test checks.
    */
   bool isSubtypeOf(TypeMirror other);
 
   /**
-   * Checks the assignability relationship, denoted by [:<=>:] in the language
-   * specification. This is the type relationship tested on assignment in
-   * checked mode.
+   * Checks the assignability relationship, denoted by `<=>` in the language
+   * specification.
+   *
+   * This is the type relationship tested on assignment in checked mode.
    */
   bool isAssignableTo(TypeMirror other);
 }
 
 /**
  * A [ClassMirror] reflects a Dart language class.
  */
 abstract class ClassMirror implements TypeMirror, ObjectMirror {
   /**
    * A mirror on the superclass on the reflectee.
@@ skipping 51 matching lines @@
    * Hence fields are not included, but the getters and setters implicitly
    * introduced by fields are included.
    *
    * The map is keyed by the simple names of the members.
    */
   Map<Symbol, MethodMirror> get staticMembers;
 
 
   /**
    * The mixin of this class.
-   * If this class is the result of a mixin application of the
-   * form S with M, returns a class mirror on M.
-   * Otherwise returns a class mirror on [reflectee].
+   *
+   * If this class is the result of a mixin application of the form S with M,
+   * returns a class mirror on M. Otherwise returns a class mirror on
+   * [reflectee].
    */
   ClassMirror get mixin;
 
   // TODO(ahe): What about:
   // /// Finds the instance member named [name] declared or inherited in the
   // /// reflected class.
   // DeclarationMirror instanceLookup(Symbol name);
 
-   /**
+  /**
    * Invokes the named constructor and returns a mirror on the result.
    *
-   * Let *c* be the class reflected by this mirror
-   * let *a1, ..., an* be the elements of [positionalArguments]
+   * Let *c* be the class reflected by this mirror,
+   * let *a1, ..., an* be the elements of [positionalArguments],
    * let *k1, ..., km* be the identifiers denoted by the elements of
-   * [namedArguments.keys]
+   * [namedArguments.keys],
    * and let *v1, ..., vm* be the elements of [namedArguments.values].
-   * If [constructorName] was created from the empty string
-   * Then this method will execute the instance creation expression
-   * *new c(a1, ..., an, k1: v1, ..., km: vm)*
-   * in a scope that has access to the private members
-   * of *c*. Otherwise, let
-   * *f* be the simple name of the constructor denoted by [constructorName]
-   * Then this method will execute the instance creation expression
-   *  *new c.f(a1, ..., an, k1: v1, ..., km: vm)*
-   * in a scope that has access to the private members
-   * of *c*.
+   *
+   * If [constructorName] was created from the empty string, then this method
+   * will execute the instance creation expression
+   * *new c(a1, ..., an, k1: v1, ..., km: vm)* in a scope that has access to
+   * the private members of *c*.
+   *
+   * Otherwise, let *f* be the simple name of the constructor denoted by
+   * [constructorName]. Then this method will execute the instance creation
+   * expression *new c.f(a1, ..., an, k1: v1, ..., km: vm)* in a scope that has
+   * access to the private members of *c*.
+   *
    * In either case:
-   * If the expression evaluates to a result *r*, this method returns
-   * the result of calling [reflect]\(*r*\).
-   * If evaluating the expression causes a compilation error
-   * the effect is the same as if a non-reflective compilation error
-   * had been encountered.
-   * If evaluating the expression throws an exception *e*
-   * (that it does not catch)
-   * this method throws *e*.
+   *
+   * * If the expression evaluates to a result *r*, this method returns the
+   *   result of calling [reflect]\(*r*\).
+   * * If evaluating the expression causes a compilation error, the effect is
+   *   the same as if a non-reflective compilation error had been encountered.
+   * * If evaluating the expression throws an exception *e* (that it does not
+   *   catch), this method throws *e*.
    */
   InstanceMirror newInstance(Symbol constructorName,
                              List positionalArguments,
                              [Map<Symbol,dynamic> namedArguments]);
 
   /**
-   * Returns [:true:] if this mirror is equal to [other].
-   * Otherwise returns [:false:].
+   * Whether this mirror is equal to [other].
    *
    * The equality holds if and only if
-   * (1) [other] is a mirror of the same kind
-   * and
-   * (2) This mirror and [other] reflect the same class.
    *
-   * Note that if the reflected class is an invocation of
-   * a generic class,(2) implies that the reflected class
-   * and [other] have equal type arguments.
+   * 1. [other] is a mirror of the same kind, and
+   * 2. This mirror and [other] reflect the same class.
+   *
+   * Note that if the reflected class is an invocation of a generic class, 2.
+   * implies that the reflected class and [other] have equal type arguments.
    */
-   bool operator == (other);
+  bool operator == (other);
 
   /**
    * Returns whether the class denoted by the receiver is a subclass of the
    * class denoted by the argument.
    *
    * Note that the subclass relationship is reflexive.
    */
   bool isSubclassOf(ClassMirror other);
 }
 
@@ skipping 14 matching lines @@
 
   /**
    * A mirror on the [:call:] method for the reflectee.
    */
   // This is only here because in the past the VM did not implement a call
   // method on closures.
   MethodMirror get callMethod;
 }
 
 /**
- * A [TypeVariableMirror] represents a type parameter of a generic
- * type.
+ * A [TypeVariableMirror] represents a type parameter of a generic type.
  */
 abstract class TypeVariableMirror extends TypeMirror {
   /**
    * A mirror on the type that is the upper bound of this type variable.
    */
   TypeMirror get upperBound;
 
   /**
    * Is the reflectee static?
    *
    * For the purposes of the mirrors library, type variables are considered
    * non-static.
    */
   bool get isStatic;
 
   /**
-   * Returns [:true:] if this mirror is equal to [other].
-   * Otherwise returns [:false:].
+   * Whether [other] is a [TypeVariableMirror] on the same type variable as this
+   * mirror.
    *
    * The equality holds if and only if
-   * (1) [other] is a mirror of the same kind
-   * and
-   * (2)  [:simpleName == other.simpleName:] and
-   * [:owner == other.owner:].
+   *
+   * 1. [other] is a mirror of the same kind, and
+   * 2. [:simpleName == other.simpleName:] and [:owner == other.owner:].
    */
-   bool operator == (other);
+  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*.
    *
+   * 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):].
    */
   FunctionTypeMirror get referent;
 }
 
 /**
  * A [MethodMirror] reflects a Dart language function, method,
  * constructor, getter, or setter.
  */
 abstract class MethodMirror implements DeclarationMirror {
@@ skipping 88 matching lines @@
    * Is the reflectee a redirecting constructor?
    */
   bool get isRedirectingConstructor;
 
   /**
    * Is the reflectee a factory constructor?
    */
   bool get isFactoryConstructor;
 
   /**
-   * Returns true if this mirror is equal to [other].
+   * Whether this mirror is equal to [other].
    *
    * The equality holds if and only if
-   * (1) [other] is a mirror of the same kind
-   * and
-   * (2) [:simpleName == other.simpleName:] and
-   * [:owner == other.owner:].
+   *
+   * 1. [other] is a mirror of the same kind, and
+   * 2. [:simpleName == other.simpleName:] and [:owner == other.owner:].
    */
-   bool operator == (other);
+  bool operator == (other);
 }
 
 /**
  * A [VariableMirror] reflects a Dart language variable declaration.
  */
 abstract class VariableMirror implements DeclarationMirror {
   /**
    * Returns a mirror on the type of the reflectee.
    */
   TypeMirror get type;
@@ skipping 13 matching lines @@
    */
   bool get isFinal;
 
   /**
    * Returns [:true:] if the reflectee is declared [:const:].
    * Otherwise returns [:false:].
    */
   bool get isConst;
 
   /**
-   * Returns true if this mirror is equal to [other].
+   * Whether this mirror is equal to [other].
    *
    * The equality holds if and only if
-   * (1) [other] is a mirror of the same kind
-   * and
-   * (2)  [:simpleName == other.simpleName:] and
-   * [:owner == other.owner:].
+   *
+   * 1. [other] is a mirror of the same kind, and
+   * 2. [:simpleName == other.simpleName:] and [:owner == other.owner:].
    */
-   bool operator == (other);
+  bool operator == (other);
 }
 
 /**
  * A [ParameterMirror] reflects a Dart formal parameter declaration.
  */
 abstract class ParameterMirror implements VariableMirror {
   /**
    * A mirror on the type of this parameter.
    */
   TypeMirror get type;
@@ skipping 10 matching lines @@
    */
   bool get isNamed;
 
   /**
    * Returns [:true:] if the reflectee has explicitly declared a default value.
    * Otherwise returns [:false:].
    */
   bool get hasDefaultValue;
 
   /**
-   * If this is a required parameter, returns [:null:]. Otherwise returns a
-   * mirror on the default value for this parameter. If no default is declared
-   * for an optional parameter, the default is [:null:] and a mirror on [:null:]
-   * is returned.
+   * Returns the default value of an optional parameter.
+   *
+   * Returns an [InstanceMirror] on the (compile-time constant)
+   * default value for an optional parameter.
+   * If no default value is declared, it defaults to `null`
+   * and a mirror of `null` is returned.
+   *
+   * Returns `null` for a required parameter.
    */
   InstanceMirror get defaultValue;
 }
 
 /**
  * A [SourceLocation] describes the span of an entity in Dart source code.
  */
 abstract class SourceLocation {
   /**
    * The 1-based line number for this source location.
@@ skipping 286 matching lines @@
   final override;
 
   /**
    * See the documentation for [MirrorsUsed.symbols], [MirrorsUsed.targets], 
    * [MirrorsUsed.metaTargets] and [MirrorsUsed.override] for documentation 
    * of the parameters.
    */
   const MirrorsUsed(
       {this.symbols, this.targets, this.metaTargets, this.override});
 }