Update comments for streams

runtime/bin/input_stream.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.
 
 /**
- * Input is read from a given input stream. Such an input stream can
- * be an endpoint, e.g., a socket or a file, or another input stream.
- * Multiple input streams can be chained together to operate collaboratively
- * on a given input.
+ * Input streams are used to read data sequentially from some data
+ * source. All input streams are non-blocking. They each have a number
+ * of read calls which will always return without any IO related
+ * blocking. If the requested data is not available a read call will
+ * return [:null:]. All input streams have one or more handlers which
+ * will trigger when data is available.
+ *
+ * The following example shows a data handler in an ordinary input
+ * stream which will be called when some data is available and a call
+ * to read will not return [:null:].
+ *
+ * [:
+ *    InputStream input = ...
+ *    input.dataHandler = () {
+ *      var data = input.read();
+ *      ...
+ *    };
+ * :]
+ *
+ * If for some reason the data from an input stream cannot be handled
+ * by the application immediately setting the data handler to [:null:]
+ * will avoid further callbacks until it is set to a functions

[Mads Ager (google), 2011/12/14 13:36:34]

a functions -> a function

[Søren Gjesse, 2011/12/14 13:41:12]

Done.

+ * again. While the data handler is not active system flow control
+ * will be used to avoid buffering more data than needed.
+ *
+ * Always set up appropriate handlers when using input streams.
+ */
+
+/**
+ * Basic input stream which supplies binary data.
  */
 interface InputStream {
   /**
    * Reads data from the stream. Returns a system allocated buffer
    * with up to [len] bytes. If no value is passed for [len] all
    * available data will be returned. If no data is available null will
    * be returned.
    */
   List<int> read([int len]);
 
@@ skipping 28 matching lines @@
   void set closeHandler(void callback());
 
   /**
    * Sets the handler that gets called when the underlying
    * communication channel gets into some kind of error situation.
    */
   void set errorHandler(void callback());
 }
 
 
+/**
+ * A string input stream wraps a basic input stream and supplies
+ * string data. This data can be read either as string chunks or as
+ * lines separated by line termination character sequences.
+ */
 interface StringInputStream factory _StringInputStream {
   /**
    * Decodes a binary input stream into characters using the specified
    * encoding.
    */
   StringInputStream(InputStream input, [String encoding]);
 
   /**
    * Reads as many characters as is available from the stream. If no data is
    * available null will be returned.
@@ skipping 40 matching lines @@
   void set closeHandler(void callback());
 
   /**
    * Sets the handler that gets called when the underlying
    * communication channel gets into some kind of error situation.
    */
   void set errorHandler(void callback());
 }
 
 
+/**
+ * A chunked input stream wraps a basic input stream and supplies
+ * binary data in configurable chunk sizes.
+ */
 interface ChunkedInputStream factory _ChunkedInputStream {
   /**
    * Adds buffering to an input stream and provide the ability to read
    * the data in known size chunks.
    */
   ChunkedInputStream(InputStream input, [int chunkSize]);
 
   /**
    * Reads [chunkSize] bytes from the stream. If [chunkSize] bytes are
    * not currently available null is returned. When the stream is
@@ skipping 36 matching lines @@
    */
   void set errorHandler(void callback());
 }
 
 
 class StreamException implements Exception {
   const StreamException([String this.message = ""]);
   String toString() => "StreamException: $message";
   final String message;
 }