Adding library level docs for async, io, convert and fixing a bug in dart:core

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.
  *
- * For an introduction to asynchronous programming in Dart, see the
- * [dart:async section of the language tour]
- * (https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-asynchronous-programming).
+ * Most programs need to use [Future]s and [Stream]s, which

[Kathy Walrath, 2013/12/16 21:18:48]

I'd delete "which are often used together".

[mem, 2013/12/16 22:18:55]

Done.

+ * are often used together, to perform asynchronous operations
+ * such as I/O.
+ * Understanding Futures and Streams is a pre-requeiste for

[Kathy Walrath, 2013/12/16 21:18:48]

requeiste: sp

I'd combine the previous paragraph and this one. Or maybe just delete the
previous one. Delete all the unnecessary wordses!

[mem, 2013/12/16 22:18:55]

Done.

+ * writing just about any Dart program.
+ *
+ * To use this library in your code:
+ *
+ *     import 'dart:async';
+ *
+ * ## Future
+ *
+ * A Future object provides a way to perform an
+ * operation asynchronously so the program doesn't block
+ * waiting for a lengthy operation to complete.
+ * Here's an example of using a Future to calculate the Fibonacci
+ * value for the number 50.
+ *
+ *     new Future(() => fibonacci(50))
+ *         .then((fibValue) { print(fibValue); })
+ *         .catchError((_) { print('An error occurred.'); });
+ *
+ * [Future.then] registers a callback function that runs
+ * when the Future's operation completes successfully.
+ * The value returned by the operation
+ * is passed into the callback function.
+ * In this example, the fibonacci function returns a number
+ * that is printed.

[Kathy Walrath, 2013/12/16 21:18:48]

I'd split this up. ("that is printed" confused me) Maybe:

In this example, the fibonacci function returns a number,
and the callback function prints that number.

[mem, 2013/12/16 22:18:55]

Done.

+ * [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.

[Kathy Walrath, 2013/12/16 21:18:48]

Put commas around "such as mouse clicks" so it's clear the bytes aren't
user-generated events.

Or switch the two examples around.

[mem, 2013/12/16 22:18:55]

Done.

+ * 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((data) {
+ *       print(data);
+ *     });
+ *
+ * The stream returns a list of bytes.
+ * The program must interpret the bytes or handle the raw byte data.
+ * Here, the code uses an UTF8 decoder (provided in the [dart:convert] library)

[Kathy Walrath, 2013/12/16 21:18:48]

an UTF8 -> a UTF8

[mem, 2013/12/16 22:18:55]

Done.

+ * because the file is a simple text file.

[Kathy Walrath, 2013/12/16 21:18:48]

the "because" didn't make sense to me.

Maybe:

to convert the file's UTF8-encoded text data into a Dart string.

[mem, 2013/12/16 22:18:55]

Done.

+ *
+ * Another common use of streams is for user-generated events
+ * in a web app. This code listens for mouse clicks on a button.

[Kathy Walrath, 2013/12/16 21:18:48]

This -> The following

AND/OR use a : instead of a .

[mem, 2013/12/16 22:18:55]

Done.

+ *
+ *     querySelector('#myButton').onClick.listen((_) { print('Click.'); } );
  *
  * ## Other resources
  *
- * * [Using Future Based APIs]
- * (https://www.dartlang.org/articles/using-future-based-apis/): A first look at
+ * * For a brief overview to asynchronous programming in Dart, see the

[Kathy Walrath, 2013/12/16 21:18:48]

to -> of

Rewrite to match the other resources (Title: Description).

[mem, 2013/12/16 22:18:55]

Done.

+ * [dart:async section of the library tour]
+ * (https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-asynchronous-programming).
+ *
+ * * [Using Future-Based APIs]

[Kathy Walrath, 2013/12/16 21:18:48]

Using -> Use

[mem, 2013/12/16 22:18:55]

Done.

+ * (https://www.dartlang.org/docs/tutorials/futures/): A closer look at
  * Futures and how to use them to write asynchronous Dart code.
  *
  * * [Futures and Error Handling]
  * (https://www.dartlang.org/articles/futures-and-error-handling/): Everything
  * you wanted to know about handling errors and exceptions when working with
  * Futures (but were afraid to ask).
  *
  * * [The Event Loop and Dart](https://www.dartlang.org/articles/event-loop/):
  * Learn how Dart handles the event queue and microtask queue, so you can write
  * better asynchronous code with fewer surprises.
@@ skipping 13 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';