Update documentation of Stream.pipe to match behavior.

sdk/lib/async/stream.dart

Index: sdk/lib/async/stream.dart
diff --git a/sdk/lib/async/stream.dart b/sdk/lib/async/stream.dart
index 3f11b91f080054036bd969eb3f7e77f3d32e12ff..b85002d5926f15b7280ee0d9c0b061ddf215a295 100644
--- a/sdk/lib/async/stream.dart
+++ b/sdk/lib/async/stream.dart
@@ -478,12 +478,19 @@ abstract class Stream<T> {
   }
 
   /**
-   * Binds this stream as the input of the provided [StreamConsumer].
+   * Pipe the events of this stream into [streamConsumer].
    *
-   * The `streamConsumer` is closed when the stream has been added to it.
+   * The `streamConsumer` is closed when this stream has been successfully added
+   * to it.
+   * If the stream produces an error, the piping will stop after that error,
+   * and the stream consumer will not be closed.
    *
    * Returns a future which completes when the stream has been consumed
-   * and the consumer has been closed.
+   * and the consumer has been closed,
+   * or after an error has made the piping stop.

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

In the error case the future completes with an error.

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

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.

+   *
+   * The [streamConsumer] should not be used for adding other events until
+   * the returned future completes.

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

In the "success" case where the streamConsumer is closed one cannot add more
events after the future completes.

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

True.
I'm not sure the behavior is actually what we want, let's check it once more.

    */
   Future pipe(StreamConsumer<T> streamConsumer) {
     return streamConsumer.addStream(this).then((_) => streamConsumer.close());