Updates documentation of StreamController.close and .done.

Fixes #19095
BUG= http://dartbug.com/19095 http://dartbug.com/27203

Change-Id: I6cbf9fb3f8151ab43da6cf47c8d4ab4282d53539
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/96600
Commit-Queue: Lasse R.H. Nielsen <lrn@google.com>
Reviewed-by: Nate Bosch <nbosch@google.com>

Author: lrhn

sdk/lib/async/stream_controller.dart

@@ -249,13 +249,40 @@ abstract class StreamController<T> implements StreamSink<T> {
   /**
    * Closes the stream.
    *
-   * Listeners receive the done event at a later microtask. This behavior can be
-   * overridden by using `sync` controllers. Note, however, that sync
-   * controllers have to satisfy the preconditions mentioned in the
-   * documentation of the constructors.
+   * No further events can be added to a closed stream.
+   *
+   * The returned future is the same future provided by [done].
+   * It is completed when the stream listeners is done sending events,
+   * This happens either when the done event has been sent,
+   * or when the subscriber on a single-subscription stream is canceled.
+   *
+   * A broadcast stream controller will send the done event
+   * even if listeners are paused, so some broadcast events may not have been
+   * received yet when the returned future completes.
+   *
+   * If noone listens to a non-broadcast stream,
+   * or the listener pauses and never resumes,
+   * the done event will not be sent and this future will never complete.
    */
   Future close();
 
+  /**
+   * A future which is completed when the stream controller is done
+   * sending events.
+   *
+   * This happens either when the done event has been sent, or if the
+   * subscriber on a single-subscription stream is canceled.
+   *
+   * A broadcast stream controller will send the done event
+   * even if listeners are paused, so some broadcast events may not have been
+   * received yet when the returned future completes.
+   *
+   * If there is no listener on a non-broadcast stream,
+   * or the listener pauses and never resumes,
+   * the done event will not be sent and this future will never complete.
+   */
+  Future get done;
+
   /**
    * Receives events from [source] and puts them into this controller's stream.
    *
@@ -575,13 +602,6 @@ abstract class _StreamController<T> implements _StreamControllerBase<T> {
     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() {

sdk_nnbd/lib/async/stream_controller.dart

@@ -245,13 +245,40 @@ abstract class StreamController<T> implements StreamSink<T> {
   /**
    * Closes the stream.
    *
-   * Listeners receive the done event at a later microtask. This behavior can be
-   * overridden by using `sync` controllers. Note, however, that sync
-   * controllers have to satisfy the preconditions mentioned in the
-   * documentation of the constructors.
+   * No further events can be added to a closed stream.
+   *
+   * The returned future is the same future provided by [done].
+   * It is completed when the stream listeners is done sending events,
+   * This happens either when the done event has been sent,
+   * or when the subscriber on a single-subscription stream is canceled.
+   *
+   * A broadcast stream controller will send the done event
+   * even if listeners are paused, so some broadcast events may not have been
+   * received yet when the returned future completes.
+   *
+   * If noone listens to a non-broadcast stream,
+   * or the listener pauses and never resumes,
+   * the done event will not be sent and this future will never complete.
    */
   Future close();
 
+  /**
+   * A future which is completed when the stream controller is done
+   * sending events.
+   *
+   * This happens either when the done event has been sent, or if the
+   * subscriber on a single-subscription stream is canceled.
+   *
+   * A broadcast stream controller will send the done event
+   * even if listeners are paused, so some broadcast events may not have been
+   * received yet when the returned future completes.
+   *
+   * If there is no listener on a non-broadcast stream,
+   * or the listener pauses and never resumes,
+   * the done event will not be sent and this future will never complete.
+   */
+  Future get done;
+
   /**
    * Receives events from [source] and puts them into this controller's stream.
    *