Format doc comments in mirrors, lines 480 through 1160

sdk/lib/mirrors/mirrors.dart

Index: sdk/lib/mirrors/mirrors.dart
diff --git a/sdk/lib/mirrors/mirrors.dart b/sdk/lib/mirrors/mirrors.dart
index 3480cdeb608a5ed821ca5570feb275f4f3a42a25..a39cdaa8b44486434cc89e0a422448208f4d16eb 100644
--- a/sdk/lib/mirrors/mirrors.dart
+++ b/sdk/lib/mirrors/mirrors.dart
@@ -479,18 +479,18 @@ abstract class InstanceMirror implements ObjectMirror {
    */
   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;
 
   /**
@@ -503,18 +503,18 @@ abstract class InstanceMirror implements ObjectMirror {
    */
   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);
 }
 
@@ -546,23 +546,22 @@ abstract class ClosureMirror implements InstanceMirror {
    */
   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]);
 }
@@ -587,18 +586,15 @@ abstract class LibraryMirror implements DeclarationMirror, ObjectMirror {
    */
   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);
 
   /**
@@ -725,17 +721,16 @@ abstract class TypeMirror implements DeclarationMirror {
   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);
 }
 
@@ -804,12 +799,11 @@ abstract class ClassMirror implements TypeMirror, ObjectMirror {
   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:
@@ -817,51 +811,46 @@ abstract class ClassMirror implements TypeMirror, ObjectMirror {
   // /// 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);
 
   /**
@@ -896,10 +885,7 @@ abstract class FunctionTypeMirror implements ClassMirror {
   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.
@@ -914,32 +900,27 @@ abstract class TypeVariableMirror extends TypeMirror {
    */
   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;
 }
 
@@ -1045,15 +1026,12 @@ abstract class MethodMirror implements DeclarationMirror {
    */
   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);
 }
 
@@ -1087,16 +1065,13 @@ abstract class VariableMirror implements DeclarationMirror {
    */
   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);
 }
 
 /**
@@ -1126,12 +1101,11 @@ abstract class ParameterMirror implements VariableMirror {
    */
   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;
 }