Update documentation for "close".

tests/lib/async/stream_controller_test.dart

 // Copyright (c) 2011, 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.
 
 // Test the basic StreamController and StreamController.singleSubscription.
 library stream_controller_test;
 
 import "package:expect/expect.dart";
 import "package:async_helper/async_helper.dart";
 import 'dart:async';
@@ skipping 401 matching lines @@
   StreamController c = new StreamController(sync: true);
   Expect.isFalse(c.isClosed);
   c.add(42);
   Expect.isFalse(c.isClosed);
   c.addError("bad");
   Expect.isFalse(c.isClosed);
   c.close();
   Expect.isTrue(c.isClosed);
 }
 
+void testCloseFuture() {
+  asyncStart();
+  asyncStart();
+  var c = new StreamController();
+  var f = c.close();
+  Expect.isTrue(c.isClosed);
+  bool doneSeen = false;
+  f.then((_) {
+    Expect.isTrue(doneSeen);
+    asyncEnd();
+  });
+  // Only listen after a while.
+  new Timer(const Duration(milliseconds: 250), () {
+    c.stream.listen(null, onDone: () {
+      asyncEnd();
+      doneSeen = true;
+    });
+  });
+}
+
+void testCloseFuture2() {
+  asyncStart();
+  asyncStart();
+  var c = new StreamController.broadcast();
+  var f = c.close();
+  Expect.isTrue(c.isClosed);
+  bool doneSeen = false;
+  f.then((_) {
+    // Done future on broadcast stream can happen
+    // before a listener is added.
+    Expect.isFalse(doneSeen);
+    asyncEnd();
+  });
+  // Only listen after a while.
+  new Timer(const Duration(milliseconds: 250), () {
+    c.stream.listen(null, onDone: () {
+      doneSeen = true;
+      asyncEnd();
+    });
+  });
+}
+
+void testCloseFuture3() {
+  asyncStart();
+  var c = new StreamController.broadcast();
+  c..add(1)..add(2)..add(3)..add(4);
+  c.stream.listen(null).cancel();
+  var f = c.close();
+  Expect.isTrue(c.isClosed);
+  f.then((_) {
+    asyncEnd();
+  });
+}
+
 void testStreamEquals() {
   StreamController c;
   c = new StreamController(sync: false);
   Expect.equals(c.stream, c.stream);
   c = new StreamController(sync: true);
   Expect.equals(c.stream, c.stream);
   c = new StreamController(sync: false, onListen:(){});
   Expect.equals(c.stream, c.stream);
   c = new StreamController(sync: true, onListen:(){});
   Expect.equals(c.stream, c.stream);
@@ skipping 92 matching lines @@
       // Only the last error ends up here.
       Expect.equals("ERROR1", e);
       asyncEnd();
     });
   });
   var addDone = c.addStream(c2.stream);
   addDone.catchError(fail).whenComplete(asyncEnd);  // Error must not go here.
   c.done.catchError(fail).whenComplete(asyncEnd); // Error must not go here.
 }
 
+void testBroadcastListenAfterClose() {
+  asyncStart();
+  StreamController c = new StreamController.broadcast();
+  var f = c.close();
+  f.then((_) {
+    // Listening after close is allowed. The listener gets a done event.
+    c.stream.listen(null, onDone: () {
+      asyncEnd();
+    });
+  });
+}
+
 main() {
   asyncStart();
   testMultiController();
   testSingleController();
   testExtraMethods();
   testClosed();
+  testCloseFuture();
+  testCloseFuture2();
+  testCloseFuture3();
   testStreamEquals();
   testCancelThrow();
   testCancelThrow2();
   testCancelThrow3();
+  testBroadcastListenAfterClose();
   asyncEnd();
 }