Warn when adding something to a closed sink and improve documentation

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 227 matching lines @@
    * A broadcast stream controller is never considered paused. It always
    * forwards its events to all uncanceled subscriptions, if any,
    * and let the subscriptions handle their own pausing and buffering.
    */
   bool get isPaused;
 
   /** Whether there is a subscriber on the [Stream]. */
   bool get hasListener;
 
   /**
-   * Send or enqueue an error event.
+   * Sends a data [event].
+   *
+   * Listeners receive this event in a later microtask.
+   *
+   * Note that a synchronous controller (created by passing true to the `sync`
+   * parameter of the `StreamController` constructor) delivers events
+   * immediately. Since this behavior violates the contract mentioned here,
+   * synchronous controllers should only be used as described in the
+   * documentation to ensure that the delivered events always *appear* as if
+   * they were delivered in a separate microtask.
+   */
+  void add(T event);
+
+  /**
+   * Sends or enqueues an error event.
    *
    * If [error] is `null`, it is replaced by a [NullThrownError].
+   *
+   * Listeners receive this 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.
    */
   void addError(Object error, [StackTrace stackTrace]);
 
   /**
+   * 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.
+   */
+  Future close();
+
+  /**
    * Receives events from [source] and puts them into this controller's stream.
    *
    * Returns a future which completes when the source stream is done.
    *
    * Events must not be added directly to this controller using [add],
    * [addError], [close] or [addStream], until the returned future
    * is complete.
    *
    * Data and error events are forwarded to this controller's stream. A done
    * event on the source will end the `addStream` operation and complete the
@@ skipping 670 matching lines @@
   var varData;
 
   _StreamControllerAddStreamState(_StreamController<T> controller, this.varData,
       Stream source, bool cancelOnError)
       : super(controller, source, cancelOnError) {
     if (controller.isPaused) {
       addSubscription.pause();
     }
   }
 }