Improve comment formatting in dart-core, especially Comparable

Improve comment formatting in dart-core, especially Comparable

R=efortuna@google.com

Committed: https://code.google.com/p/dart/source/detail?r=31698

[Alan Knight, 2014-01-09 17:47:14]

In the new dartdoc-viewer I noticed that the comments for Comparable did not
format well.
 
https://dartdoc-next-dot-dartlang-api.appspot.com/apidocs/channels/be/#dart-c...

Fixed them up, and made a quick pass through other things in core to turn a few
things into references rather than backquoted code and other minor fixes.

[Emily Fortuna, 2014-01-09 18:21:57]

lgtm with some adjustments

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/function.dart
File sdk/lib/core/function.dart (right):

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/function.dart#n...
sdk/lib/core/function.dart:29: * gives exactly the same result as
should we add an extra line between 28 and 29?

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/set.dart
File sdk/lib/core/set.dart (right):

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/set.dart#newcode36
sdk/lib/core/set.dart:36: * have a compatible [dart-core.Object.hashCode]
implementation.
shouldn't need the dart-core....

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/string_sink.dart
File sdk/lib/core/string_sink.dart (right):

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/string_sink.dar...
sdk/lib/core/string_sink.dart:10: * Converts [obj] to a String by invoking
[dart-core.Object.toString] and
You shouldn't need to put the full name here. Just [toString] should suffice.

[Alan Knight, 2014-01-09 18:47:28]

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/function.dart
File sdk/lib/core/function.dart (right):

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/function.dart#n...
sdk/lib/core/function.dart:29: * gives exactly the same result as
On 2014/01/09 18:21:57, Emily Fortuna wrote:
> should we add an extra line between 28 and 29?

Done.

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/set.dart
File sdk/lib/core/set.dart (right):

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/set.dart#newcode36
sdk/lib/core/set.dart:36: * have a compatible [dart-core.Object.hashCode]
implementation.
On 2014/01/09 18:21:57, Emily Fortuna wrote:
> shouldn't need the dart-core....

Weird. For some reason it had seemed like I needed that, but looking again it
doesn't even work. Removed here and throughout.

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/string_sink.dart
File sdk/lib/core/string_sink.dart (right):

https://codereview.chromium.org/131793004/diff/1/sdk/lib/core/string_sink.dar...
sdk/lib/core/string_sink.dart:10: * Converts [obj] to a String by invoking
[dart-core.Object.toString] and
On 2014/01/09 18:21:57, Emily Fortuna wrote:
> You shouldn't need to put the full name here. Just [toString] should suffice.

Done.

[Alan Knight, 2014-01-10 18:51:00]

Committed patchset #2 manually as r31698 (presubmit successful).

[Kathy Walrath, 2014-01-10 18:57:51]

lgtm