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

sdk/lib/convert/convert.dart

Index: sdk/lib/convert/convert.dart
diff --git a/sdk/lib/convert/convert.dart b/sdk/lib/convert/convert.dart
index 8cdc936993aff2722594fe21a9f5b6c26782acff..1073eb2fa9bcc25d6ebda1228709781da2f8319a 100644
--- a/sdk/lib/convert/convert.dart
+++ b/sdk/lib/convert/convert.dart
@@ -5,6 +5,42 @@
 /**
  * Converters for JSON and UTF-8, as well as support for creating additional
  * converters.
+ *
+ * The dart:convert library works in both web apps and command-line apps.
+ * To use it:
+ *
+ *     import 'dart:convert';
+ *
+ * Two commonly used converters are the top-level instances of
+ * [JsonCodec] and [Utf8Codec], named JSON and UTF8, respectively.
+ * JSON is a simple text format for representing
+ * structured objects and collections.
+ * UTF-8 is a common variable-width encoding that can represent
+ * every character in the Unicode character set.
+ *
+ * Converters are often used in conjunction with streams

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

in conjunction with -> with

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

Done.

+ * transforming the data that comes through the stream

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

transforming -> to transform

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

Done.

+ * as it becomes available.
+ * The following code uses two converters.
+ * The first is a UTF8 decoder, which converts the data from bytes to UTF-8
+ * as it's read from a file,
+ * The second is an instance of [LineSplitter],
+ * which splits the data on newline boundaries.
+ *
+ *     int lineNumber = 1;
+ *     Stream<List<int>> stream = new File('quotes.txt').openRead();
+ *
+ *     stream.transform(UTF8.decoder)
+ *           .transform(const LineSplitter())
+ *           .listen((line) {
+ *             if (showLineNumbers) {
+ *               stdout.write('${lineNumber++} ');
+ *             }
+ *             stdout.writeln(line);
+ *           });
+ *
+ * See the documentation for the [Codec] and the [Converter] classes

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

and the -> and

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

Done.

+ * for information about creating your own converters.
  */
 library dart.convert;