Update documentation for "close".

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 f953a5a276709316157ec34ddb7f7e7ddcd44fa1..e73d3f6c76fa30dd2984445ffcd3b76c7cdf5932 100644
--- a/sdk/lib/async/stream.dart
+++ b/sdk/lib/async/stream.dart
@@ -1338,11 +1338,11 @@ abstract class StreamSubscription<T> {
  * An interface that abstracts creation or handling of [Stream] events.
  */
 abstract class EventSink<T> implements Sink<T> {
-  /** Create a data event */
+  /** Create a data event on the stream. */

[Anders Johnsen, 2014/06/02 10:18:08]

Send a ...? (and below)

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

Done.

   void add(T event);
-  /** Create an async error. */
+  /** Create an async error on the stream. */
   void addError(errorEvent, [StackTrace stackTrace]);
-  /** Request a stream to close. */
+  /** Request a stream to close. This should also create a done event.*/
   void close();
 }
 
@@ -1387,6 +1387,12 @@ abstract class StreamConsumer<S> {
    */
   Future addStream(Stream<S> stream);
 
+  /**
+   * Tell the consumer that no futher streams will be added.
+   *
+   * Returns a future that is completed when the consumer is done handling
+   * events.
+   */
   Future close();
 }
 
@@ -1410,17 +1416,22 @@ abstract class StreamConsumer<S> {
  */
 abstract class StreamSink<S> implements StreamConsumer<S>, EventSink<S> {
   /**
-   * Close the [StreamSink]. It'll return the [done] Future.
+   * As [EventSink.close], but also returns a future.
+   *
+   * Returns a future which is completed when the close operation is complete.
+   * If closing can fail for a particular `StreamSink`, the future will then
+   * contain the error.
    */
   Future close();
 
   /**
-   * The [done] Future completes with the same values as [close], except
-   * for the following case:
+   * Return a future which is completed when the [StreamSink] is cloed.

[Anders Johnsen, 2014/06/02 10:18:08]

cloed -> closed

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

Reworded entire comment.

+   *
+   * If adding events using [add] and [addError] can fail, the [done] future
+   * will then contain the error.

[Anders Johnsen, 2014/06/02 10:18:08]

contain -> complete with

    *
-   * * The synchronous methods of [EventSink] were called, resulting in an
-   *   error. If there is no active future (like from an addStream call), the
-   *   [done] future will complete with that error
+   * If [close] is called, the returned future will complete with the same
+   * result as the future returned by `close`.

[Anders Johnsen, 2014/06/02 10:18:08]

the same result -> the same future (too complex to read, otherwise).

    */
   Future get done;
 }