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

sdk/lib/convert/convert.dart

 // Copyright (c) 2013, 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.
 
 /**
  * Converters for JSON and UTF-8, as well as support for creating additional

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

I think the first line should be updated to something like this.

Library for handling conversion between different data representations. It
provides support for implementing converters in a way which makes them easy to
chaining and work well with streams.

It includes a number of converters including ones for JSON and UTF-8.

Converters implemented using the 

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

Your comment drifted off....

Anyway, the convention for the first line is that it's a one-liner and starts
with a noun phrase. So I put in your changes with some alteration to stay within
this constraint.

  * converters.
+ *
+ * The dart:convert library works in both web apps and command-line apps.

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

Wrap dart:convert in backquotes (`dart:convert`) for formatting?

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

Done.

+ * To use it:
+ *
+ *     import 'dart:convert';
+ *
+ * Two commonly used converters are the top-level instances of
+ * [JsonCodec] and [Utf8Codec], named JSON and UTF8, respectively.

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

Add empty line before "JSON" and before "UTF-8" below.

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

Done.

+ * JSON is a simple text format for representing

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

I think we should be a bit more precise about the JSON and UTF-8 converters. Say
that JSON transforms between object structures strings using the JSON format,
and that UTF-8 transfors between Strings and bytes.

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

Agree.

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

Done.

+ * 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 with streams
+ * to transform the data that comes through the stream
+ * 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 [Converter] classes
+ * for information about creating your own converters.
  */
 library dart.convert;
 
 import 'dart:async';
 import "dart:collection" show HashSet;
 
 part 'ascii.dart';
 part 'byte_conversion.dart';
 part 'chunked_conversion.dart';
 part 'codec.dart';
 part 'converter.dart';
 part 'encoding.dart';
 part 'html_escape.dart';
 part 'json.dart';
 part 'latin1.dart';
 part 'line_splitter.dart';
 part 'string_conversion.dart';
 part 'utf.dart';