Documentation cleanups.

sdk/lib/async/stream.dart

 // Copyright (c) 2013, 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;
 
 // -------------------------------------------------------------------
 // Core Stream types
 // -------------------------------------------------------------------
 
@@ skipping 1360 matching lines @@
  * When you listen on a [Stream] using [Stream.listen],
  * a [StreamSubscription] object is returned.
  *
  * The subscription provides events to the listener,
  * and holds the callbacks used to handle the events.
  * The subscription can also be used to unsubscribe from the events,
  * or to temporarily pause the events from the stream.
  */
 abstract class StreamSubscription<T> {
   /**
-   * Cancels this subscription. It will no longer receive events.
+   * Cancels this subscription.
    *
-   * May return a future which completes when the stream is done cleaning up.
-   * This can be used if the stream needs to release some resources
-   * that are needed for a following operation,
-   * for example a file being read, that should be deleted afterwards.
-   * In that case, the file may not be able to be deleted successfully
-   * until the returned future has completed.
+   * After this call it does no longer receive events. However, the cleanup of

[Lasse Reichstein Nielsen, 2016/02/09 16:34:53]

"After this call returns, the subscription no longer receives events.

The stream may need to shut down the source of events and clean up after the
subscription is cancelled."

[floitsch, 2016/02/09 17:26:51]

Done.

+   * the stream might not be finished yet.
    *
-   * The future will be completed with a `null` value.
+   * Returns `null` if the cleanup is finished, or a future otherwise.
+   * In the latter case, the future is completed once the stream has finished
+   * its cleanup.

[Lasse Reichstein Nielsen, 2016/02/09 16:34:53]

I would focus on returning a future - we have many places where we return a
pre-completed future even if there is no cleanup, returning null is just the
special case that we can't get rid of.

Something like:
  Returns a future which completes after cleanup is done.
  May return `null` if there is no further cleanup.

[floitsch, 2016/02/09 17:26:51]

Done.

+   *
+   * Typically, futures are returned when the stream needs to release resources.
+   * For example, a stream might need to close an open file (as an asynchronous
+   * operation). If the listener wants to delete the file after having
+   * canceled the subscription, it must wait for the cleanup future to complete.
+   *
+   * A returned future completes with a `null` value.
    * If the cleanup throws, which it really shouldn't, the returned future
-   * will be completed with that error.
-   *
-   * Returns `null` if there is no need to wait.
+   * completes with that error.
    */
   Future cancel();
 
   /**
    * Set or override the data event handler of this subscription.
    *
    * This method overrides the handler that has been set at the invocation of
    * [Stream.listen].
    */
   void onData(void handleData(T data));
@@ skipping 391 matching lines @@
 class _ControllerEventSinkWrapper<T> implements EventSink<T> {
   EventSink _sink;
   _ControllerEventSinkWrapper(this._sink);
 
   void add(T data) { _sink.add(data); }
   void addError(error, [StackTrace stackTrace]) {
     _sink.addError(error, stackTrace);
   }
   void close() { _sink.close(); }
 }