Update documentation for "close".

sdk/lib/async/stream_controller.dart

 // Copyright (c) 2012, 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;
 
 // -------------------------------------------------------------------
 // Controller for creating and adding events to a stream.
 // -------------------------------------------------------------------
 
@@ skipping 364 matching lines @@
     _StreamControllerAddStreamState addState =
         new _StreamControllerAddStreamState(this,
                                             _varData,
                                             source,
                                             cancelOnError);
     _varData = addState;
     _state |= _STATE_ADDSTREAM;
     return addState.addStreamFuture;
   }
 
+  /**
+   * Returns a future that is completed when the stream is done
+   * processing events.
+   *
+   * This happens either when the done event has been sent, or if the
+   * subscriber of a single-subscription stream is cancelled.
+   */
   Future get done => _ensureDoneFuture();
 
   Future _ensureDoneFuture() {
     if (_doneFuture == null) {
       _doneFuture = _isCanceled ? Future._nullFuture : new _Future();
     }
     return _doneFuture;
   }
 
   /**
    * Send or enqueue a data event.
    */
   void add(T value) {
     if (!_mayAddEvent) throw _badEventState();
     _add(value);
   }
 
   /**
    * Send or enqueue an error event.
    */
   void addError(Object error, [StackTrace stackTrace]) {
     if (!_mayAddEvent) throw _badEventState();
     _addError(error, stackTrace);
   }
 
   /**
-   * Closes this controller.
+   * Closes this controller and sends a done event on the stream.
    *
-   * After closing, no further events may be added using [add] or [addError].
+   * The first time a controller is closed, a "done" event is added to its
+   * stream.
    *
    * You are allowed to close the controller more than once, but only the first
    * call has any effect.
    *
-   * The first time a controller is closed, a "done" event is sent to its
-   * stream.
+   * After closing, no further events may be added using [add] or [addError].
+   *
+   * The returned future is completed when the done event has been delivered.
    */
   Future close() {
     if (isClosed) {
       return _ensureDoneFuture();
     }
     if (!_mayAddEvent) throw _badEventState();
     _state |= _STATE_CLOSED;
     if (hasListener) {
       _sendDone();
     } else if (_isInitialState) {
@@ skipping 329 matching lines @@
   _StreamControllerAddStreamState(_StreamController controller,
                                   this.varData,
                                   Stream source,
                                   bool cancelOnError)
       : super(controller, source, cancelOnError) {
     if (controller.isPaused) {
       addSubscription.pause();
     }
   }
 }