Fix documentation in dart:io.

sdk/lib/async/async.dart

 // Copyright (c) 2012, 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.
 
 /**
  * Support for asynchronous programming,
  * with classes such as Future and Stream.
  *
  * Understanding [Future]s and [Stream]s is a prerequisite for
  * writing just about any Dart program.
@@ skipping 25 matching lines @@
  * The value returned by the operation
  * is passed into the callback function.
  * In this example, the `bind()` method returns the HttpServer
  * object. The callback function prints one of its properties.
  * [Future.catchError] registers a callback function that
  * runs if an error occurs within the Future.
  *
  * ## Stream
  *
  * A Stream provides an asynchronous sequence of data.
- * Examples of data sequences include user-generated events,
- * such as mouse clicks, and a stream of bytes read from a file.
+ * Examples of data sequences include individual events, like mouse clicks,
+ * or sequential chunks of larger data, like multiple byte lists with the
+ * contents of a file
+ * such as mouse clicks, and a stream of byte lists read from a file.
  * The following example opens a file for reading.
  * [Stream.listen] registers a callback function that runs
  * each time more data is available.
  *
  *     Stream<List<int>> stream = new File('quotes.txt').openRead();
  *     stream.transform(UTF8.decoder).listen(print);
  *
  * The stream emits a sequence of a list of bytes.
  * The program must interpret the bytes or handle the raw byte data.
  * Here, the code uses a UTF8 decoder (provided in the `dart:convert` library)
@@ skipping 39 matching lines @@
 part 'future.dart';
 part 'future_impl.dart';
 part 'schedule_microtask.dart';
 part 'stream.dart';
 part 'stream_controller.dart';
 part 'stream_impl.dart';
 part 'stream_pipe.dart';
 part 'stream_transformers.dart';
 part 'timer.dart';
 part 'zone.dart';