Update documentation for "close".

Update documentation for "close" and fix subscription returned by closed broadcast streams.

The close method on StreamConsumer, StreamSink and StreamController do not explain
the returned future or say when it is completed.

Listening on a closed broadcast stream should not throw, but just give a subscription that sends a done asap.

BUG= http://dartbug.com/19095
R=ajohnsen@google.com

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

[Lasse Reichstein Nielsen, 2014-06-02 07:21:51]

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

https://codereview.chromium.org/301193010/diff/1/sdk/lib/async/stream.dart#ne...
sdk/lib/async/stream.dart:1435: // TODO: What does this mean?
I've tried to read the previous documentation, and I don't understand what it
says. Can you say what the intent of this was?

[Anders Johnsen, 2014-06-02 08:22:50]

lgtm, with comments.

https://codereview.chromium.org/301193010/diff/20001/sdk/lib/async/broadcast_...
File sdk/lib/async/broadcast_stream_controller.dart (right):

https://codereview.chromium.org/301193010/diff/20001/sdk/lib/async/broadcast_...
sdk/lib/async/broadcast_stream_controller.dart:317: Future _callOnCancel() {
I see no return statements?

https://codereview.chromium.org/301193010/diff/20001/sdk/lib/async/stream.dart
File sdk/lib/async/stream.dart (right):

https://codereview.chromium.org/301193010/diff/20001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1419: * Send a done event, as the [EventSink.close].
The wording is a bit confusing. At first, I though it would send a 'done' event
of the form 'EventSink.close'. :)

https://codereview.chromium.org/301193010/diff/20001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1435: // TODO: What does this mean?
"If [add] or [addError] is called and the operation results in a asynchronous
error, that error is forwarded to the [done] future. If [close] is called,
[close] will return the same [Future] as [done]."

Better?

[Lasse Reichstein Nielsen, 2014-06-02 09:48:25]

Added more changes. PTAL.

https://codereview.chromium.org/301193010/diff/20001/sdk/lib/async/broadcast_...
File sdk/lib/async/broadcast_stream_controller.dart (right):

https://codereview.chromium.org/301193010/diff/20001/sdk/lib/async/broadcast_...
sdk/lib/async/broadcast_stream_controller.dart:317: Future _callOnCancel() {
And I don't remember making this change. Odd.

https://codereview.chromium.org/301193010/diff/20001/sdk/lib/async/stream.dart
File sdk/lib/async/stream.dart (right):

https://codereview.chromium.org/301193010/diff/20001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1419: * Send a done event, as the [EventSink.close].
Reworded.

https://codereview.chromium.org/301193010/diff/20001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1435: // TODO: What does this mean?
Better. I think I know what you mean.
I'll try rewriting.

[Anders Johnsen, 2014-06-02 10:18:04]

lgtm

https://codereview.chromium.org/301193010/diff/60001/sdk/lib/async/stream.dart
File sdk/lib/async/stream.dart (right):

https://codereview.chromium.org/301193010/diff/60001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1341: /** Create a data event on the stream. */
Send a ...? (and below)

https://codereview.chromium.org/301193010/diff/60001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1428: * Return a future which is completed when the
[StreamSink] is cloed.
cloed -> closed

https://codereview.chromium.org/301193010/diff/60001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1431: * will then contain the error.
contain -> complete with

https://codereview.chromium.org/301193010/diff/60001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1434: * result as the future returned by `close`.
the same result -> the same future (too complex to read, otherwise).

[Lasse Reichstein Nielsen, 2014-06-02 10:52:53]

https://codereview.chromium.org/301193010/diff/60001/sdk/lib/async/stream.dart
File sdk/lib/async/stream.dart (right):

https://codereview.chromium.org/301193010/diff/60001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1341: /** Create a data event on the stream. */
On 2014/06/02 10:18:08, Anders Johnsen wrote:
> Send a ...? (and below)

Done.

https://codereview.chromium.org/301193010/diff/60001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1428: * Return a future which is completed when the
[StreamSink] is cloed.
Reworded entire comment.

[Anders Johnsen, 2014-06-02 10:58:39]

lgtm with comments

https://codereview.chromium.org/301193010/diff/80001/sdk/lib/async/stream.dart
File sdk/lib/async/stream.dart (right):

https://codereview.chromium.org/301193010/diff/80001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1419: * As [EventSink.close], but also returns a
future.
Is 'also' correct?... :)

https://codereview.chromium.org/301193010/diff/80001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1428: * If the `StreamSink` can stop working due to an
error,
If the StreamSink produces an error, perhaps ...

https://codereview.chromium.org/301193010/diff/80001/sdk/lib/async/stream.dar...
sdk/lib/async/stream.dart:1433: * when all events have been processed and the
sink has been closed,
... when:

* All events ...

or

* When the ...

[Lasse Reichstein Nielsen, 2014-06-02 11:04:07]

Committed patchset #6 manually as r36862 (presubmit successful).