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..9105d3557dde75fd4ac195604a090636d8ca05bf 100644
--- a/sdk/lib/async/stream.dart
+++ b/sdk/lib/async/stream.dart
@@ -478,12 +478,22 @@ 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 added
+   * to it.
+   *
+   * If the stream produces an error, the piping will stop after that error.
    *
    * Returns a future which completes when the stream has been consumed
    * and the consumer has been closed.
+   *
+   * The returned future completes with the same result as the future returned
+   * by [StreamConsumer.close].
+   * If the adding of the stream itself fails in some way,
+   * then the consumer is expected to be closed, and won't be closed again.

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

Why 'is expected'? Sounds a bit vague.

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

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. 

+   * In that case the returned future completes with the error from adding
+   * the stream.
    */
   Future pipe(StreamConsumer<T> streamConsumer) {
     return streamConsumer.addStream(this).then((_) => streamConsumer.close());