Update documentation of StreamSubscription.cancel.

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 4b29de8c0a6f842b926557b54f5f9eb7b23e961a..8f1eaecda70cb4ecab0b7c031b34243a66668115 100644
--- a/sdk/lib/async/stream.dart
+++ b/sdk/lib/async/stream.dart
@@ -1168,11 +1168,13 @@ 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`.
+   * Returns a future that 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 should not be deleted until the returned future

[Anders Johnsen, 2014/04/29 09:46:01]

[...], the file may not be deleted [...].

+   * has completed.
+   * May return `null` if there is no need to wait.

[Lasse Reichstein Nielsen, 2014/04/29 09:17:53]

Do we still return null?

[Anders Johnsen, 2014/04/29 09:46:01]

Yes, sometimes

    */
   Future cancel();