Update documentation for "close".

tests/lib/async/stream_controller_test.dart

Index: tests/lib/async/stream_controller_test.dart
diff --git a/tests/lib/async/stream_controller_test.dart b/tests/lib/async/stream_controller_test.dart
index 6cb1e69f0ad2555187c52a197d6a2b39e6908039..4fadf693d8ccdb2e07c39fe4f917dea814c0d7de 100644
--- a/tests/lib/async/stream_controller_test.dart
+++ b/tests/lib/async/stream_controller_test.dart
@@ -419,6 +419,60 @@ void testClosed() {
   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);
@@ -531,15 +585,31 @@ void testCancelThrow3() {
   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();
 }