Update documentation for "close".

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 1320 matching lines @@
    * [futureValue].
    */
   Future asFuture([var futureValue]);
 }
 
 
 /**
  * An interface that abstracts creation or handling of [Stream] events.
  */
 abstract class EventSink<T> implements Sink<T> {
-  /** Create a data event */
+  /** Send a data event to a stream. */
   void add(T event);
-  /** Create an async error. */
+  /** Send an async error to a stream. */
   void addError(errorEvent, [StackTrace stackTrace]);
-  /** Request a stream to close. */
+  /** Send a done event to a stream.*/
   void close();
 }
 
 
 /** [Stream] wrapper that only exposes the [Stream] interface. */
 class StreamView<T> extends Stream<T> {
   Stream<T> _stream;
 
   StreamView(this._stream);
 
@@ skipping 24 matching lines @@
   /**
    * Consumes the elements of [stream].
    *
    * Listens on [stream] and does something for each event.
    *
    * The consumer may stop listening after an error, or it may consume
    * all the errors and only stop at a done event.
    */
   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();
 }
 
 
 /**
  * A [StreamSink] unifies the asynchronous methods from [StreamConsumer] and
  * the synchronous methods from [EventSink].
  *
  * The [EventSink] methods can't be used while the [addStream] is called.
  * As soon as the [addStream]'s [Future] completes with a value, the
  * [EventSink] methods can be used again.
  *
  * If [addStream] is called after any of the [EventSink] methods, it'll
  * be delayed until the underlying system has consumed the data added by the
  * [EventSink] methods.
  *
  * When [EventSink] methods are used, the [done] [Future] can be used to
  * catch any errors.
  *
  * When [close] is called, it will return the [done] [Future].
  */
 abstract class StreamSink<S> implements StreamConsumer<S>, EventSink<S> {
   /**
-   * Close the [StreamSink]. It'll return the [done] Future.
+   * As [EventSink.close], but returns a future.
+   *
+   * Returns the same future as [done].
    */
   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 finished.
    *
-   * * 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 the `StreamSink` fails with an error,
+   * perhaps in response to adding events using [add], [addError] or [close],
+   * the [done] future will complete with that error.
+   *
+   * Otherwise, the returned future will complete when either:
+   *
+   * * all events have been processed and the sink has been closed, or
+   * * the sink has otherwise been stopped from handling more events
+   *   (for example by cancelling a stream subscription).
    */
   Future get done;
 }
 
 
 /**
  * The target of a [Stream.transform] call.
  *
  * The [Stream.transform] call will pass itself to this object and then return
  * the resulting stream.
@@ skipping 149 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(); }
 }