Format doc comments in mirrors, lines 480 through 1160

Format doc comments in mirrors, lines 480 through 1160

BUG=https://github.com/dart-lang/sdk/issues/24505

Committed: https://github.com/dart-lang/sdk/commit/e928812e277cb41e13177bb995e31e6d2558089a

[sethladd, 2015-10-06 17:20:04]

sethladd@google.com changed reviewers:
+ lrn@google.com, sethladd@google.com

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

Why are we changing the comment style on existing libraries?

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dart
File sdk/lib/mirrors/mirrors.dart (right):

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:482: /// Does [reflectee] contain the instance
reflected by this mirror?
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."

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:555: /// method invocation *f(a1, ..., an, k1: v1,
..., km: vm)*
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).

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:724: /// Checks the subtype relationship, denoted
by [:<::] in the language
You can change [:...:] to `...` too, while you are here (if you can be bothered
- it may help with some long lines).

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:819: /// be the elements of
[namedArguments.values].
Again a reflow that makes reading/editing harder.

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:845: /// Otherwise returns [:false:].
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.

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:905: /// Otherwise returns [:false:].
Again, maybe change to "Whether [other] is a [TypeVariableMirror] on the same
type variable as this mirror.".


Dittos for all other operator=='s.

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:1104: /// If this is a required parameter, returns
[:null:].
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:52]

Thansk for the review. Reverted to the other comment style.

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dart
File sdk/lib/mirrors/mirrors.dart (right):

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:482: /// Does [reflectee] contain the instance
reflected by this mirror?
On 2015/10/07 08:27:55, Lasse Reichstein Nielsen wrote:
> 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."

Done.

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:555: /// method invocation *f(a1, ..., an, k1: v1,
..., km: vm)*
On 2015/10/07 08:27:55, Lasse Reichstein Nielsen wrote:
> 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).

Done.

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:724: /// Checks the subtype relationship, denoted
by [:<::] in the language
On 2015/10/07 08:27:55, Lasse Reichstein Nielsen wrote:
> You can change [:...:] to `...` too, while you are here (if you can be
bothered
> - it may help with some long lines).

Done.

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:819: /// be the elements of
[namedArguments.values].
On 2015/10/07 08:27:55, Lasse Reichstein Nielsen wrote:
> Again a reflow that makes reading/editing harder.

Done.

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:845: /// Otherwise returns [:false:].
On 2015/10/07 08:27:55, Lasse Reichstein Nielsen wrote:
> 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.

Done.

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:905: /// Otherwise returns [:false:].
On 2015/10/07 08:27:55, Lasse Reichstein Nielsen wrote:
> Again, maybe change to "Whether [other] is a [TypeVariableMirror] on the same
> type variable as this mirror.".
> 
> 
> Dittos for all other operator=='s.

Done.

https://codereview.chromium.org/1390813002/diff/1/sdk/lib/mirrors/mirrors.dar...
sdk/lib/mirrors/mirrors.dart:1104: /// If this is a required parameter, returns
[:null:].
On 2015/10/07 08:27:55, Lasse Reichstein Nielsen wrote:
> 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.

Done.

[srawlins, 2015-10-07 23:42:04]

Committed patchset #2 (id:20001) manually as
e928812e277cb41e13177bb995e31e6d2558089a (presubmit successful).