Warn when adding something to a closed sink and improve documentation

sdk/lib/async/stream.dart

Index: sdk/lib/async/stream.dart
diff --git a/sdk/lib/async/stream.dart b/sdk/lib/async/stream.dart
index 48c40637c1e432fabdd56637e5339edb76d04860..59a35329e14ab8b3fcb869ae89d177d475f5c7f5 100644
--- a/sdk/lib/async/stream.dart
+++ b/sdk/lib/async/stream.dart
@@ -1463,16 +1463,28 @@ abstract class StreamSubscription<T> {
 }
 
 /**
- * An interface that abstracts creation or handling of [Stream] events.
+ * A [Sink] that supports adding errors and closing.

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

The [Sink] already supports closing, so it's redundant to mention here, so just
"... that supports adding errors."

Perhaps also say that this makes it suitable for capturing the results of
asynchronous *computations* (which can complete with a value *or* an error).

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

Done.

  */
 abstract class EventSink<T> implements Sink<T> {

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

The name "EventSink" comes from streams, so I'm not sure removing the reference
to streams in the documentation is really necessary.
If it is, maybe we should rename this sink to AsyncSink (which we won't because
it's breaking, but still!).
So, make some sort of documentation about what an "event" is in the class
documentation, because it's needed as context for the name (and the "event" uses
below).

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

Added a paragraph:
 * The [EventSink] has been designed to handle asynchronous events from
 * [Stream]s. See, for example, [Stream.eventTransformed] which uses
 * `EventSink`s to transform events.

I agree, that the name is not great, but I don't think we should change the name
to `AsyncSink`. That's a misnomer as well.

-  /** Send a data event to a stream. */
+  /**
+   * Puts a data [event] into the sink.

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

Puts .. into -> Adds .. to

We generally use "add" about what we do to sinks.
Dittos below.

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

Done.

+   *
+   * Must not be called on a closed sink.
+   */
   void add(T event);
 
-  /** Send an async error to a stream. */
+  /**
+   * Puts an [errorEvent] into the sink.
+   *
+   * Must not be called on a closed sink.
+   */
   void addError(Object errorEvent, [StackTrace stackTrace]);

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

Hmm, errorEvent -> error.
It's suspicious that the error is an event and the stackTrace isn't. And it's
not clear what event is (unless you write it somewhere, in which case you
probably don't need to repeat it here anyway).

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

Done.

 
-  /** Close the sink. No further events can be added after closing. */
+  /**
+   * Closes the sink.
+   *
+   * No further events can be added after closing.

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

Can you close more than once?

What is an event? (that should be documented in the class doc, as stated above).

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

   * Calling this method more than once is allowed, but does nothing.
   *
   * Neither [add] nor [addError] must be called after this method.

done.

+   */
   void close();
 }
 
@@ -1505,10 +1517,6 @@ class StreamView<T> extends Stream<T> {
  * and when no further data need to be added, the [close] method tells the
  * consumer to complete its work and shut down.
  *
- * This class is not just a [Sink<Stream>] because it is also combined with
- * other [Sink] classes, like it's combined with [EventSink] in the
- * [StreamSink] class.
- *
  * The [Stream.pipe] accepts a `StreamConsumer` and will pass the stream
  * to the consumer's [addStream] method. When that completes, it will
  * call [close] and then complete its own returned future.
@@ -1550,8 +1558,7 @@ abstract class StreamConsumer<S> {
 /**
  * A object that accepts stream events both synchronously and asynchronously.
  *
- * A [StreamSink] unifies the asynchronous methods from [StreamConsumer] and
- * the synchronous methods from [EventSink].
+ * A [StreamSink] combines the methods from [StreamConsumer] and [EventSink].
  *
  * The [EventSink] methods can't be used while the [addStream] is called.
  * As soon as the [addStream]'s [Future] completes with a value, the