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 217 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 at a later microtask. This behavior can be

[Lasse Reichstein Nielsen, 2017/04/26 08:26:19]

at -> in (or as). 
A microtask has a duration, it's not a point in time, so I don't think "at"
applies - but that's obviously a subjective idea :)

[floitsch, 2017/05/01 16:46:25]

Done.

+   * overridden by using `sync` controllers. Note, however, that sync

[Lasse Reichstein Nielsen, 2017/04/26 08:26:19]

Overridden means something else (you override a method), so it's somewhat
confusing to use it here with a different meaning - even if it's technically
correct.

How about:

Note that a synchronous controller (created by passing true for the `sync`
parameter of the `StreamController` constructor) delivers events immediately, so
they must be used as described in the documentation of the constructor to ensure
that the delivered events always *appear* to be in a separate microtask.

[floitsch, 2017/05/01 16:46:25]

   * 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.

done.

+   * controllers have to satisfy the preconditions mentioned in the
+   * documentation of the constructors.
+   */
+  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();
     }
   }
 }