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

sdk/lib/io/io.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.
 
 /**
  * File, socket, HTTP, and other I/O support for server applications.
  *
- * The IO library is used for Dart server applications,
+ * The I/O library is used for Dart server applications,
  * which run on a stand-alone Dart VM from the command line.
- * *This library does not work in browser based applications.*
+ * *This library does not work in browser-based applications.*
  *
  * This library allows you to work with files, directories,
  * sockets, processes, HTTP servers and clients, and more.
+ *
+ * To use this library in your code:
+ *
+ *     import 'dart:io';
+ *
+ * Many operations related to input and output are asynchronous
+ * and are handled using Futures or Streams.
+ * Consider it a pre-requisite to learn about Futures and Streams

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

pre-requisite -> prerequisite

"Consider it ..." seems weak.

Actually, I'd just delete that sentence and most of the next. (just leave in the
mention of dart:async, and put the links to [Future] and [Stream] in the
previous sentence.

And delete "import 'dart:async'".

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

Done.

+ * before learning about I/O.
+ * The [Future] and [Stream] classes are in the [dart:async] library.
+ *
+ *     import 'dart:async';
+ *
+ * ## FileSystemEntity
+ *
+ * Given a pathname, you can create a [FileSystemEntity] to represent
+ * whatever is at that pathname.
+ * Then you can query the FileSystemEntity object to get information
+ * using methods such as 'isDirectory', 'isFile', and 'exists'.
+ * Because these methods

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

Maybe:

Because file system access can be slow, these methods are asynchronous and
return a Future.

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

Done.

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

Done.

+ * must access the file system to determine the answer,
+ * the operations are performed asynchronously with a Future.
+ *
+ *     FileSystemEntity.isDirectory(myPath).then((isDir) {
+ *       if (isDir) {
+ *         print('$myPath is a directory');
+ *       } else {
+ *         print('$myPath is not a directory');
+ *       }
+ *     });
+ *
+ * ## File and Directory
+ *
+ * A [File] object represents a file in the native file system.
+ * A [Directory] object represents a directory in the native file system.

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

This is choppy. Maybe:

Each instance of [File] or [Directory] represents a file or directory,
respectively, in the native file system.
Both File and Directory are subclasses of ....

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

Done.

+ * Both are subclasses of FileSystemEntity.
+ * You can manipulate the file sytem through objects of these types.

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

sytem!

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

Done.

+ * For example, you can rename a file or directory:
+ *
+ *     File myFile = new File('myFile.txt');
+ *     myFile.rename('yourFile.txt').then((_) { print('file renamed'); });
+ *
+ * Many methods provided by the File and Directory classes
+ * run asynchronously and return a Future.
+ *
+ * ## HttpServer
+ *
+ * To create an Http server, we recommend that you try using
+ * the [http_server](https://pub.dartlang.org/packages/http_server)
+ * pub package, which contains
+ * a set of high-level classes that, together with the [HttpServer] class
+ * in this library, makes it easy to provide content through HTTP servers.
+ *
+ * ## Standard output, error, and input streams
+ *
+ * This library provides the standard output, error, and input
+ * streams, named 'stdout', 'stderr', and 'stdin', respectively.
+ *
+ * The stdout and stderr streams are both [IOSink]s and have the same set
+ * of methods and properties.
+ *
+ * To write a string to 'stdout':
+ *
+ *     stdout.writeln('Hello, World!');
+ *
+ * To write a list of objects to 'stderr':
+ *
+ *     stderr.writeAll([ 'That ', 'is ', 'an ', 'error.', '\n']);
+ *
+ * The standard input stream is a true [Stream], so it inherits
+ * properties and methods from the Stream class.
+ *
+ * To read text synchronously from the command-line

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

command-line -> command line
(since it's not an adjectival phrase modifying a noun)

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

Done.

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

Done.

+ * (the program blocks waiting for user to type information):
+ *
+ *      String inputText = stdin.readLineSync();
+ *
+ * ## Other Resources

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

Resources -> resources

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

Done.

+ *
+ * For an introduction to I/O in Dart, see the
+ * [dart:io section of the library tour]
+ * (https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-dartio---file-and-socket-io-for-command-line-apps).
+ *
+ * To learn more about I/O in Dart, refer to the
+ * [tutorial about writing command-line apps]
+ * (https://www.dartlang.org/docs/tutorials/dartio/).

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

I think the URL should be either dart-io or io. probably just io...

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

Done.

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

Done.

  */
 library dart.io;
 
 import 'dart:async';
 import 'dart:_collection-dev';
 import 'dart:collection' show HashMap,
                               HashSet,
                               LinkedList,
                               LinkedListEntry;
 import 'dart:convert';
@@ skipping 24 matching lines @@
 part 'platform_impl.dart';
 part 'process.dart';
 part 'socket.dart';
 part 'stdio.dart';
 part 'string_transformer.dart';
 part 'timer_impl.dart';
 part 'secure_socket.dart';
 part 'secure_server_socket.dart';
 part 'websocket.dart';
 part 'websocket_impl.dart';