Update documentation of Stream.pipe to match behavior.

Update documentation of Stream.pipe to match behavior.

R=sgjesse@google.com

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

[Lasse Reichstein Nielsen, 2015-06-17 09:01:38]

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

[Søren Gjesse, 2015-06-17 10:56:04]

lgtm

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

https://codereview.chromium.org/1189873004/diff/1/sdk/lib/async/stream.dart#n...
sdk/lib/async/stream.dart:490: * or after an error has made the piping stop.
In the error case the future completes with an error.

https://codereview.chromium.org/1189873004/diff/1/sdk/lib/async/stream.dart#n...
sdk/lib/async/stream.dart:493: * the returned future completes.
In the "success" case where the streamConsumer is closed one cannot add more
events after the future completes.

[Søren Gjesse, 2015-06-18 08:00:14]

lgtm

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

https://codereview.chromium.org/1189873004/diff/20001/sdk/lib/async/stream.da...
sdk/lib/async/stream.dart:494: * then the consumer is expected to be closed, and
won't be closed again.
Why 'is expected'? Sounds a bit vague.

[Lasse Reichstein Nielsen, 2015-06-18 08:47:06]

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

https://codereview.chromium.org/1189873004/diff/1/sdk/lib/async/stream.dart#n...
sdk/lib/async/stream.dart:490: * or after an error has made the piping stop.
Nope. Would be nice, but that's not what is happening.
We do the addStream, which has a default of cancelOnError: true.
That means that an error in the original stream will put one error into the
consumer and then stop. 
Only if the addStream return future contains an error will we get an error here
(and not close the consumer).

So I'm wrong - the consumer is closed even if the stream contained an error,
it's just closed after the first error.

https://codereview.chromium.org/1189873004/diff/1/sdk/lib/async/stream.dart#n...
sdk/lib/async/stream.dart:493: * the returned future completes.
True.
I'm not sure the behavior is actually what we want, let's check it once more.

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

https://codereview.chromium.org/1189873004/diff/20001/sdk/lib/async/stream.da...
sdk/lib/async/stream.dart:494: * then the consumer is expected to be closed, and
won't be closed again.
Because the StreamConsumer.addStream documentation doesn't say anything
non-vague.

I've changed the text to explicitly refer to addStream, since it has similar
vague behavior, and you may want to know that it is what is being used so you
can check your own consumer.

[Søren Gjesse, 2015-06-18 08:48:57]

lgtm

[Lasse Reichstein Nielsen, 2015-06-18 11:03:19]

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