Clean-up of Future documentation and small fix-ups.

Clean-up of Future documentation and small fix-ups.

R=floitsch@google.com

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

[Lasse Reichstein Nielsen, 2017-05-31 14:20:52]

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

[floitsch, 2017-05-31 15:28:28]

LGTM.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart
File sdk/lib/async/future.dart (right):

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:64: * In some cases we say that a future is completed
with another future.
Put a line before here. (I think this should be a new paragraph).

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:65: * In that case, the other future is waited for,
and when it completes,
... with another future. This is a short way of stating that the future is
completed in the same way, with the same value or error, as the other future
(once it completes). Whenever a function in the core library may complete a
future (for example [Completer.complete] or [new Future.value]), then it also
accepts another Future and does this work for the developer.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:145: /// A `Future<Null>` completed with `null`.
Should we make this one public? It's quite common.

Probably not in this CL.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:240: * Creates a future completed with [result].
a future, completed with...

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:242: * If [result] is a future, this creates a new
future that waits for the
"this creates" sounds bad.

The created future waits for ...

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:243: * [result] future to complete, and then completes
with the same result.
Maybe mention that this means that a Future.value may be completed with an
error.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:245: * If [result] is not a [Future], this creates a
future that is already
not a [Future], the returned future

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:246: * completed with th [result] value
the

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:251: factory Future.value([FutureOr<T> result]) {
"result" sounds weird.
Probably just "value"?

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:287: * after microtasks have run.
after all microtasks

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:617: * ```
I would just remove this example. Way too complicated and not adding anything.

Otherwise, it should be a paragraph earlier.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:855: /** The future completed by this completer. */
It's not always completed yet.

maybe?
The future that this completer manages.
The future owned by this completer.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:899: * Actually reflects whether [complete] or
[completeError] has been called.
Remove "Actually".

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:900: * If [complete] is called with a future, the
actual completion my happen
That sounds wrong (and I interpreted it the wrong way).

A true value does not mean that listeners of the future have been invoked yet.
This could be, because completers generally wait one microtask before
propagating completion values, or, because the completion value was a future.

[Lasse Reichstein Nielsen, 2017-06-02 05:53:39]

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart
File sdk/lib/async/future.dart (right):

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:64: * In some cases we say that a future is completed
with another future.
On 2017/05/31 15:28:27, floitsch wrote:
> Put a line before here. (I think this should be a new paragraph).

Done.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:65: * In that case, the other future is waited for,
and when it completes,
Used with slight rewording.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:145: /// A `Future<Null>` completed with `null`.
I'd want to iterate a little on the name if we make it public, but it's probably
a good idea now that a `Future<Null>` is a future of any type.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:240: * Creates a future completed with [result].
Don't think that would work, there'd be no subject after the comma.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:242: * If [result] is a future, this creates a new
future that waits for the
Done.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:245: * If [result] is not a [Future], this creates a
future that is already
On 2017/05/31 15:28:27, floitsch wrote:
> not a [Future], the returned future

Done + reworded.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:246: * completed with th [result] value
On 2017/05/31 15:28:28, floitsch wrote:
> the

Done.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:251: factory Future.value([FutureOr<T> result]) {
On 2017/05/31 15:28:27, floitsch wrote:
> "result" sounds weird.
> Probably just "value"?

Done.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:287: * after microtasks have run.
OK, but technically not correct - there might be more microtasks in the next
event. It's also not all current microtasks, because it's also after the
microtasks triggered by those.

To be precise, it's after "the microtask queue has become empty", but I didn't
want to write that (it's not that easy to understand), so I went for the vague
but suggestive "after micotasks have run".

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:617: * ```
Removed.

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:855: /** The future completed by this completer. */
I think it can work as written. "Completed by" can be both past and future tense
(has been or will be).

Neither "manages" nor "owns" really describe the relation, and we'd have to
describe what that means anyway.

Reworded to "the future that is completed by this completer".

https://codereview.chromium.org/2917683002/diff/1/sdk/lib/async/future.dart#n...
sdk/lib/async/future.dart:900: * If [complete] is called with a future, the
actual completion my happen
Reworded to something like that. 
(It doesn't wait *one* microtask, it may be many microtasks later).

[Lasse Reichstein Nielsen, 2017-06-02 05:56:24]

Description was changed from

==========
Clean-up of Future documentation and small fix-ups.
==========

to

==========
Clean-up of Future documentation and small fix-ups.

R=floitsch@google.com

Committed:
https://github.com/dart-lang/sdk/commit/2a14e68d78e8fb5bb4478bc719c57597673b3a6f
==========

[Lasse Reichstein Nielsen, 2017-06-02 05:56:26]

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