Update documentation of Stream.pipe to match behavior.

sdk/lib/async/stream.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.async;
 
 // -------------------------------------------------------------------
 // Core Stream types
 // -------------------------------------------------------------------
 
@@ skipping 460 matching lines @@
    *
    * The returned stream is a broadcast stream if this stream is.
    * If a broadcast stream is listened to more than once, each subscription
    * will individually call `convert` and expand the events.
    */
   Stream expand(Iterable convert(T value)) {
     return new _ExpandStream<T, dynamic>(this, convert);
   }
 
   /**
-   * 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());
   }
 
   /**
    * Chains this stream as the input of the provided [StreamTransformer].
    *
    * Returns the result of [:streamTransformer.bind:] itself.
    *
@@ skipping 1216 matching lines @@
 class _ControllerEventSinkWrapper<T> implements EventSink<T> {
   EventSink _sink;
   _ControllerEventSinkWrapper(this._sink);
 
   void add(T data) { _sink.add(data); }
   void addError(error, [StackTrace stackTrace]) {
     _sink.addError(error, stackTrace);
   }
   void close() { _sink.close(); }
 }