Index: sdk/lib/async/stream.dart |
diff --git a/sdk/lib/async/stream.dart b/sdk/lib/async/stream.dart |
index 510cccb93d0b9f1044d696bd35b464479e91821d..5dae80290008abad69a35e647cad83b085ea79e7 100644 |
--- a/sdk/lib/async/stream.dart |
+++ b/sdk/lib/async/stream.dart |
@@ -1378,20 +1378,24 @@ abstract class Stream<T> { |
*/ |
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, the subscription no longer receives events. |
* |
- * The future will be completed with a `null` value. |
- * If the cleanup throws, which it really shouldn't, the returned future |
- * will be completed with that error. |
+ * The stream may need to shut down the source of events and clean up after |
+ * the subscription is canceled. |
+ * |
+ * Returns a future that is completed once the stream has finished |
+ * its cleanup. May also return `null` if no cleanup was necessary. |
* |
- * Returns `null` if there is no need to wait. |
+ * 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 |
+ * completes with that error. |
*/ |
Future cancel(); |