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 461 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.
-   *
-   * 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]
-   */
+  /// Does [reflectee] contain the instance reflected by this mirror?

[Lasse Reichstein Nielsen, 2015/10/07 08:27:55]

Reword to not be a question. And it's not entirely sensical as written -
variables don't "contain" values.

I would prefer "Whether [reflectee] will return the instance reflected by this
mirror."

[srawlins, 2015/10/07 10:50:51]

Done.

+  ///
+  /// 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]
   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].
-   * 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.
-   */
+  /// Returns true if 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.
   bool operator == (other);
 }
 
 /**
  * A [ClosureMirror] reflects a closure.
  *
  * A [ClosureMirror] provides the ability to execute its reflectee and
  * introspect its function.
  */
 abstract class ClosureMirror implements InstanceMirror {
@@ skipping 11 matching lines @@
    * [:type.declarations[#call]:]. But the Dart language model does not require
    * this. A more typical implementation involves a single closure class for
    * 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 *k1, ..., km* be the identifiers denoted by the elements of
-   * [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*.
-   */
+  /// 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 *k1, ..., km* be the identifiers
+  /// denoted by the elements of [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)*

[Lasse Reichstein Nielsen, 2015/10/07 08:27:55]

The line breaking of the original was actually very readable, and therefore
editable if needed.
Consider *not* changing line flow when the original lines still fit.
(The "new" dartdoc format uses one more character per line, so it might not
always be possible).

[srawlins, 2015/10/07 10:50:51]

Done.

+  ///
+  /// 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:].
-   *
-   * 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.
-   */
+  /// Returns [:true:] if this mirror is equal to [other].
+  ///
+  /// Otherwise returns [:false:].
+  ///
+  /// 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.
    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 {
@@ 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

[Lasse Reichstein Nielsen, 2015/10/07 08:27:55]

You can change [:...:] to `...` too, while you are here (if you can be bothered
- it may help with some long lines).

[srawlins, 2015/10/07 10:50:51]

Done.

+  /// 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 48 matching lines @@
    *
    * The intent is to capture those members that constitute the API of a class.
    * 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].
-   */
+  /// 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].
   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 *k1, ..., km* be the identifiers denoted by the elements of
-   * [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*.
-   * 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*.
-   */
+  /// 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 *k1, ..., km* be the identifiers
+  /// denoted by the elements of [namedArguments.keys], and let *v1, ..., vm*
+  /// be the elements of [namedArguments.values].

[Lasse Reichstein Nielsen, 2015/10/07 08:27:55]

Again a reflow that makes reading/editing harder.

[srawlins, 2015/10/07 10:50:51]

Done.

+  ///
+  /// 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*.
   InstanceMirror newInstance(Symbol constructorName,
                              List positionalArguments,
                              [Map<Symbol,dynamic> namedArguments]);
 
-  /**
-   * Returns [:true:] if this mirror is equal to [other].
-   * Otherwise returns [:false:].
-   *
-   * 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.
-   */
+  /// Returns [:true:] if this mirror is equal to [other].
+  ///
+  /// Otherwise returns [:false:].

[Lasse Reichstein Nielsen, 2015/10/07 08:27:55]

Maybe replace by:
"Whether [other] is a [ClassMirror] of the same class as this mirror."

We already know that the return type is bool, saying it returns true or false
seems redundant.

[srawlins, 2015/10/07 10:50:51]

Done.

+  ///
+  /// 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.
    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 @@
   List<ParameterMirror> get parameters;
 
   /**
    * 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:].
-   *
-   * 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:].
-   */
-   bool operator == (other);
+  /// Returns [:true:] if this mirror is equal to [other].
+  ///
+  /// Otherwise returns [:false:].

[Lasse Reichstein Nielsen, 2015/10/07 08:27:55]

Again, maybe change to "Whether [other] is a [TypeVariableMirror] on the same
type variable as this mirror.".


Dittos for all other operator=='s.

[srawlins, 2015/10/07 10:50:51]

Done.

+  ///
+  /// 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:].
+  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*.
-   *
-   * For instance [:void f(int):] is the referent for [:typedef void f(int):].
-   */
+  /// 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):].
   FunctionTypeMirror get referent;
 }
 
 /**
  * A [MethodMirror] reflects a Dart language function, method,
  * constructor, getter, or setter.
  */
 abstract class MethodMirror implements DeclarationMirror {
   /**
    * A mirror on the return type for the reflectee.
@@ skipping 85 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].
-   *
-   * 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:].
-   */
+  /// Returns true if 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:].
    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.
    */
@@ skipping 13 matching lines @@
    * Otherwise returns [:false:].
    */
   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].
-   *
-   * 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:].
-   */
-   bool operator == (other);
+  /// Returns true if 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:].
+  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;
 
   /**
    * Returns [:true:] if the reflectee is an optional parameter.
    * Otherwise returns [:false:].
    */
   bool get isOptional;
 
   /**
    * Returns [:true:] if the reflectee is a named parameter.
    * Otherwise returns [:false:].
    */
   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.
-   */
+  /// If this is a required parameter, returns [:null:].

[Lasse Reichstein Nielsen, 2015/10/07 08:27:55]

Start by describing what it is/does, leave exceptions until after all useful
information.

/// 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.

[srawlins, 2015/10/07 10:50:51]

Done.

+  ///
+  /// 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.
   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 285 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});
 }