Modernize the package's style.

Modernize the package's style.

This moves the package to new-style doc comments, deprecates separate
top-level libraries, and removes library tags. It also deprecates some
top-level classes in favor of static const fields.

There's more that could be done, but this fixes most of the low-hanging
fruit.

R=lrn@google.com

Committed: https://github.com/dart-lang/async/commit/66843f16c9becf164229e72ec5e04b205332a5f9

[nweiz, 2016-03-08 03:20:05]

nweiz@google.com changed reviewers:
+ lrn@google.com

[nweiz, 2016-03-08 03:20:06]

I'd really like to be able to commit this tomorrow, so the package can by
stylistically up-to-date when my post about it goes live.

[Lasse Reichstein Nielsen, 2016-03-08 10:40:37]

lgtm

https://codereview.chromium.org/1777453002/diff/1/lib/src/async_memoizer.dart
File lib/src/async_memoizer.dart (right):

https://codereview.chromium.org/1777453002/diff/1/lib/src/async_memoizer.dart...
lib/src/async_memoizer.dart:41: /// If [run] has already been called, this
returns the original result.
run->runOnce

https://codereview.chromium.org/1777453002/diff/1/lib/src/future_group.dart
File lib/src/future_group.dart (right):

https://codereview.chromium.org/1777453002/diff/1/lib/src/future_group.dart#n...
lib/src/future_group.dart:36: /// Returns `true` if this group isn't waiting on
any futures.
A getter is no different from a (final) field.
I'd prefer to document it like a filed, that is: as a property, not a function.
Returning is something that functions do - it's describing the *behavior* of the
function, not what it *is*.

https://codereview.chromium.org/1777453002/diff/1/lib/src/result.dart
File lib/src/result.dart (right):

https://codereview.chromium.org/1777453002/diff/1/lib/src/result.dart#newcode24
lib/src/result.dart:24: /// error events.
You can refer to `captureStream` here. This is the transformer that
`captureStream` uses, and that you can use if you want to chain calls to
transform.

Similar for the transformers below.

https://codereview.chromium.org/1777453002/diff/1/lib/src/result.dart#newcode75
lib/src/result.dart:75: static _captureValue(value) => new ValueResult(value);
Can we use `ValueResult#` instead of `_captureValue` now, or is it still not
implemented everywhere?

https://codereview.chromium.org/1777453002/diff/1/lib/src/result/capture_tran...
File lib/src/result/capture_transformer.dart (right):

https://codereview.chromium.org/1777453002/diff/1/lib/src/result/capture_tran...
lib/src/result/capture_transformer.dart:11: @Deprecated("Will be removed in
async 2.0.0.")
Just @Deprecated("in async 2.0.0")
The Deprecated class has a toString method that adds "will be removed" before
the text.

[nweiz, 2016-03-08 20:21:55]

Code review changes

[nweiz, 2016-03-08 20:23:35]

Code review changes

[nweiz, 2016-03-08 20:23:41]

https://codereview.chromium.org/1777453002/diff/1/lib/src/async_memoizer.dart
File lib/src/async_memoizer.dart (right):

https://codereview.chromium.org/1777453002/diff/1/lib/src/async_memoizer.dart...
lib/src/async_memoizer.dart:41: /// If [run] has already been called, this
returns the original result.
On 2016/03/08 10:40:37, Lasse Reichstein Nielsen wrote:
> run->runOnce

Done.

https://codereview.chromium.org/1777453002/diff/1/lib/src/future_group.dart
File lib/src/future_group.dart (right):

https://codereview.chromium.org/1777453002/diff/1/lib/src/future_group.dart#n...
lib/src/future_group.dart:36: /// Returns `true` if this group isn't waiting on
any futures.
On 2016/03/08 10:40:37, Lasse Reichstein Nielsen wrote:
> A getter is no different from a (final) field.
> I'd prefer to document it like a filed, that is: as a property, not a
function.
> Returning is something that functions do - it's describing the *behavior* of
the
> function, not what it *is*.

Done.

https://codereview.chromium.org/1777453002/diff/1/lib/src/result.dart
File lib/src/result.dart (right):

https://codereview.chromium.org/1777453002/diff/1/lib/src/result.dart#newcode24
lib/src/result.dart:24: /// error events.
On 2016/03/08 10:40:37, Lasse Reichstein Nielsen wrote:
> You can refer to `captureStream` here. This is the transformer that
> `captureStream` uses, and that you can use if you want to chain calls to
> transform.
> 
> Similar for the transformers below.

Done.

https://codereview.chromium.org/1777453002/diff/1/lib/src/result.dart#newcode75
lib/src/result.dart:75: static _captureValue(value) => new ValueResult(value);
On 2016/03/08 10:40:37, Lasse Reichstein Nielsen wrote:
> Can we use `ValueResult#` instead of `_captureValue` now, or is it still not
> implemented everywhere?

I believe it's not implemented anywhere but the VM.

https://codereview.chromium.org/1777453002/diff/1/lib/src/result/capture_tran...
File lib/src/result/capture_transformer.dart (right):

https://codereview.chromium.org/1777453002/diff/1/lib/src/result/capture_tran...
lib/src/result/capture_transformer.dart:11: @Deprecated("Will be removed in
async 2.0.0.")
On 2016/03/08 10:40:37, Lasse Reichstein Nielsen wrote:
> Just @Deprecated("in async 2.0.0")
> The Deprecated class has a toString method that adds "will be removed" before
> the text.

I'm mostly concerned with how it appears in dartdoc, where it just includes the
literal annotation contents:
https://www.dartdocs.org/documentation/http_parser/2.2.0/http_parser/WebSocke...

[nweiz, 2016-03-08 20:24:21]

Description was changed from

==========
Modernize the package's style.

This moves the package to new-style doc comments, deprecates separate
top-level libraries, and removes library tags. It also deprecates some
top-level classes in favor of static const fields.

There's more that could be done, but this fixes most of the low-hanging
fruit.
==========

to

==========
Modernize the package's style.

This moves the package to new-style doc comments, deprecates separate
top-level libraries, and removes library tags. It also deprecates some
top-level classes in favor of static const fields.

There's more that could be done, but this fixes most of the low-hanging
fruit.

R=lrn@google.com

Committed:
https://github.com/dart-lang/async/commit/66843f16c9becf164229e72ec5e04b20533...
==========

[nweiz, 2016-03-08 20:24:22]

Committed patchset #3 (id:40001) manually as
66843f16c9becf164229e72ec5e04b205332a5f9 (presubmit successful).