Change and structure how Stream implementations do callbacks.

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 8394c007ae78108820a4307cd8a070efde2a7244..9ea10f52cb35788d7578e7fe6203d9fc4095b202 100644
--- a/sdk/lib/async/stream_controller.dart
+++ b/sdk/lib/async/stream_controller.dart
@@ -19,6 +19,32 @@ part of dart.async;
  * It's possible to check whether the stream is paused or not, and whether
  * it has subscribers or not, as well as getting a callback when either of
  * these change.
+ *
+ * If the stream starts or stops having listeners (first listener subscribing,
+ * last listener unsubscribing), the `onSubscriptionStateChange` callback
+ * is notified as soon as possible. If the subscription stat changes during
+ * an event firing or a callback being executed, the change will not be reported
+ * until the current event or callback has finished.
+ * If the pause state has also changed during an event or callback, only the
+ * subscription state callback is notified.
+ *
+ * If the subscriber state has not changed, but the pause state has, the
+ * `onPauseStateChange` callback is notified as soon as possible, after firing
+ * a current event or completing another callback. This happens if the stream
+ * is not paused, and a listener pauses it, or if the stream has been resumed
+ * from pause and has no pending events. If the listeners resume a paused stream
+ * while it still has queued events, the controller will still consider the
+ * stream paused until all queued events have been dispatched.
+ *
+ * Whether to invoke a callback depends only on the state before and after
+ * a stream action, for example firing an event. If the state changes multiple
+ * times during the action, and then ends up in the same state as before, no
+ * callback is performed.
+ *
+ * If listeners are added after the stream has completed (sent a "done" event),
+ * the listeners will be sent a "done" event eventually, but they won't affect
+ * the stream at all, and won't trigger callbacks. From the controller's point
+ * of view, the stream is completely inert when has completed.
  */
 class StreamController<T> implements StreamSink<T> {
   final _StreamImpl<T> stream;
@@ -72,7 +98,7 @@ class StreamController<T> implements StreamSink<T> {
   bool get isClosed => stream._isClosed;
 
   /** Whether one or more active subscribers have requested a pause. */
-  bool get isPaused => stream._isPaused;
+  bool get isPaused => stream._isInputPaused;
 
   /** Whether there are currently any subscribers on this [Stream]. */
   bool get hasSubscribers => stream._hasSubscribers;