specify when a Future completes for IOSink's addStream

sdk/lib/io/io_sink.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.io;
 
 /**
  * Helper class to wrap a [StreamConsumer<List<int>>] and provide
  * utility functions for writing to the StreamConsumer directly. The
  * [IOSink] buffers the input given by all [StringSink] methods and will delay
@@ skipping 78 matching lines @@
    *
    * This function must not be called when a stream is currently being added
    * using [addStream].
    *
    * This operation is non-blocking. See [flush] or [done] for how to get any
    * errors generated by this call.
    */
   void addError(error, [StackTrace stackTrace]);
 
   /**
-   * Adds all elements of the given [stream] to `this`.
+   * Returns a [Future] that completes when

[Lasse Reichstein Nielsen, 2015/09/21 09:50:47]

Retain the original first line, then add these two as well (after an empty
line).

We usually have a simple first line that describes what happens.
Then , after an empty line, we describe in more detail what parameters means and
what is returned.
A doc that starts with "Returns ..." is generally reserved for getters (or
functions which should probably have been getters).

[sethladd, 2015/09/21 09:56:21]

Done.

+   * all elements of the given [stream] are added to `this`.
    */
   Future addStream(Stream<List<int>> stream);
 
   /**
    * Returns a [Future] that completes once all buffered data is accepted by the
    * to underlying [StreamConsumer].
    *
    * It's an error to call this method, while an [addStream] is incomplete.
    *
    * NOTE: This is not necessarily the same as the data being flushed by the
@@ skipping 186 matching lines @@
 
   void writeln([Object obj = ""]) {
     write(obj);
     write("\n");
   }
 
   void writeCharCode(int charCode) {
     write(new String.fromCharCode(charCode));
   }
 }