Update documentation of StreamSubscription.cancel.

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 1150 matching lines @@
  *
  * When you subscribe on a [Stream] using [Stream.listen],
  * a [StreamSubscription] object is returned. This object
  * is used to later unsubscribe again, or to temporarily pause
  * the stream's events.
  */
 abstract class StreamSubscription<T> {
   /**
    * Cancels this subscription. It will no longer receive events.
    *
-   * If an event is currently firing, this unsubscription will only
-   * take effect after all subscribers have received the current event.
-   *
-   * Returns a future if the cancel-operation is not completed synchronously.
-   * Otherwise returns `null`.
+   * 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.
+   * Returns `null` if there is no need to wait.
    */
   Future cancel();
 
   /** Set or override the data event handler of this subscription. */
   void onData(void handleData(T data));
 
   /**
    * Set or override the error event handler of this subscription.
    *
    * This method overrides the handler that has been set at the invocation of
@@ skipping 296 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(); }
 }