Index: sdk/lib/async/stream.dart |
diff --git a/sdk/lib/async/stream.dart b/sdk/lib/async/stream.dart |
index 2220d068aaeea5b4a57fb23ccead7f80558ec20d..64a525f1f30dcd6d7ae258c35bc761661c8f4ab5 100644 |
--- a/sdk/lib/async/stream.dart |
+++ b/sdk/lib/async/stream.dart |
@@ -1532,16 +1532,37 @@ abstract class StreamSubscription<T> { |
} |
/** |
- * An interface that abstracts creation or handling of [Stream] events. |
+ * A [Sink] that supports adding errors. |
+ * |
+ * This makes it suitable for capturing the results of asynchronous |
+ * computations, which can complete with a value or an error. |
+ * |
+ * The [EventSink] has been designed to handle asynchronous events from |
+ * [Stream]s. See, for example, [Stream.eventTransformed] which uses |
+ * `EventSink`s to transform events. |
*/ |
abstract class EventSink<T> implements Sink<T> { |
- /** Send a data event to a stream. */ |
+ /** |
+ * Adds a data [event] to the sink. |
+ * |
+ * Must not be called on a closed sink. |
+ */ |
void add(T event); |
- /** Send an async error to a stream. */ |
- void addError(Object errorEvent, [StackTrace stackTrace]); |
+ /** |
+ * Adds an [error] to the sink. |
+ * |
+ * Must not be called on a closed sink. |
+ */ |
+ void addError(Object error, [StackTrace stackTrace]); |
- /** Close the sink. No further events can be added after closing. */ |
+ /** |
+ * Closes the sink. |
+ * |
+ * Calling this method more than once is allowed, but does nothing. |
+ * |
+ * Neither [add] nor [addError] must be called after this method. |
+ */ |
void close(); |
} |
@@ -1574,10 +1595,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. |
@@ -1619,8 +1636,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 |