Warn when adding something to a closed sink and improve documentation

sdk/lib/async/stream_controller.dart

Index: sdk/lib/async/stream_controller.dart
diff --git a/sdk/lib/async/stream_controller.dart b/sdk/lib/async/stream_controller.dart
index 1f15703dd2853843a962623a709947828c1301e7..06697d35d9b7c9f906e9ea994275a3bcfe9d9e3e 100644
--- a/sdk/lib/async/stream_controller.dart
+++ b/sdk/lib/async/stream_controller.dart
@@ -235,13 +235,38 @@ abstract class StreamController<T> implements StreamSink<T> {
   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.