Document that IOSink.add may buffer data.

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
  * a [addStream] until the buffer is flushed.
  *
  * When the [IOSink] is bound to a stream (through [addStream]) any call
  * to the [IOSink] will throw a [StateError]. When the [addStream] compeltes,
  * the [IOSink] will again be open for all calls.
  */
 abstract class IOSink implements StreamSink<List<int>>, StringSink {
   factory IOSink(StreamConsumer<List<int>> target,
                  {Encoding encoding: Encoding.UTF_8})
       => new _IOSinkImpl(target, encoding);
 
   /**
    * The [Encoding] used when writing strings. Depending on the
    * underlying consumer this property might be mutable.
    */
   Encoding encoding;
 
   /**
-   * Writes the bytes uninterpreted to the consumer.
+   * Writes the bytes uninterpreted to the consumer. While the call is
+   * synchronous, the data may be buffered until the underlying resource is
+   * ready. The data should not be modified after a call to [add].
    */
   void add(List<int> data);
 
   /**
    * Writes an error to the consumer.
    */
   void addError(error);
 
   /**
    * Adds all elements of the given [stream] to `this`.
@@ skipping 176 matching lines @@
 
   void writeln([Object obj = ""]) {
     write(obj);
     write("\n");
   }
 
   void writeCharCode(int charCode) {
     write(new String.fromCharCode(charCode));
   }
 }