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 390 matching lines @@
 
   /**
    * 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].
    *
    * 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
+   * The first time a controller is closed, a "done" event is added to its
    * stream.
+   *
+   * 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();
     }
   }
 }