Update comments for streams

runtime/bin/input_stream.dart

Index: runtime/bin/input_stream.dart
diff --git a/runtime/bin/input_stream.dart b/runtime/bin/input_stream.dart
index 300f50e77b52010292bf00930022ec22df2edf90..d77c3628848eb309bc3fb7fe25a8c7b2fc8ca5b4 100644
--- a/runtime/bin/input_stream.dart
+++ b/runtime/bin/input_stream.dart
@@ -3,10 +3,36 @@
 // 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 {
   /**
@@ -55,6 +81,11 @@ interface InputStream {
 }
 
 
+/**
+ * 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
@@ -115,6 +146,10 @@ interface StringInputStream factory _StringInputStream {
 }
 
 
+/**
+ * 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