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

sdk/lib/async/async.dart

Index: sdk/lib/async/async.dart
diff --git a/sdk/lib/async/async.dart b/sdk/lib/async/async.dart
index a565220cfdcd622d992893d37cdffcd7ad0df809..d2bbcffbdc191810f4c74b42b223d95067928fb6 100644
--- a/sdk/lib/async/async.dart
+++ b/sdk/lib/async/async.dart
@@ -6,14 +6,66 @@
  * 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).
+ * Understanding Futures and Streams is a prerequisite for
+ * 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.

[Søren Gjesse, 2013/12/19 09:44:40]

This is not really true in this example. As each Dart isolate is single-threaded
delaying the calculation of fibonacci(50) using new Future(() => fibonacci(50))
will run the computation using Timer.run. When the timer fires for the
computation the program will block for this computation to complete.

For Dart code to really run in the background spawning an isolate is needed. For
this intro I think it is better to use some dart:io and dart:html future as the
stream examples below.

I think the definition from the Future class is better "A Future is used to
obtain a not yet available value, or error, sometime in the future.". It defines
what it is (but not the numerous ways they can be created).

[Lasse Reichstein Nielsen, 2013/12/19 15:22:49]

Agree.
I see a future as representing a computation that might not have completed yet.
It doesn't provide functionality to do async stuff, it is just the result.

[mem, 2013/12/19 23:24:24]

Done.

+ * 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); })

[Søren Gjesse, 2013/12/19 09:44:40]

Use the => syntax everywhere?

[Lasse Reichstein Nielsen, 2013/12/19 15:22:49]

Or not even that; in this case, you can just write
  .then(print)

+ *         .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,
+ * and the callback function prints that number.
+ * [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.
+ * 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) {

[Søren Gjesse, 2013/12/19 09:44:40]

Shorten to

stream.transform(UTF8.decoder).listen(print)

?

[mem, 2013/12/19 23:24:24]

Done.

+ *       print(data);
+ *     });
+ *
+ * The stream returns a list of bytes.

[Søren Gjesse, 2013/12/19 09:44:40]

The stream emits a sequence of list of bytes (depending how the file reader
provides its data).

[mem, 2013/12/19 23:24:24]

Done.

+ * 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)

[Lasse Reichstein Nielsen, 2013/12/19 15:22:49]

Does [dart:convert] work as a DartDoc link?

[mem, 2013/12/19 23:24:24]

no but it should.
I was optimistic.

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

[Søren Gjesse, 2013/12/19 09:44:40]

Maybe be more explicit on saying that the converter emits a sequence of strings.

[mem, 2013/12/19 23:24:24]

Done.

+ *
+ * Another common use of streams is for user-generated events
+ * in a web app: The following code listens for mouse clicks on a button.
+ *
+ *     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
+ * * The [dart:async section of the library tour]
+ * (https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-asynchronous-programming):
+ * A brief overview of asynchronous programming.
+ *
+ * * [Use Future-Based APIs]
+ * (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]