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

sdk/lib/io/io.dart

Index: sdk/lib/io/io.dart
diff --git a/sdk/lib/io/io.dart b/sdk/lib/io/io.dart
index 1cf9c4d3999a2d01fc97c60475e1f8e651d756e9..d1e5516c075d2799a523f9d3de801ffd330012ad 100644
--- a/sdk/lib/io/io.dart
+++ b/sdk/lib/io/io.dart
@@ -5,12 +5,93 @@
 /**
  * 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 [Future]s or [Stream]s, both of which
+ * are in the [dart:async] library.

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

are in -> are defined in

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

Done.

+ *
+ * ## FileSystemEntity
+ *
+ * Given a pathname, you can create a [FileSystemEntity] to represent

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

It is not possible to create a FileSystemEntity object directly. It is has not
public constructors. It is an abstract superclass for File, Directory and Link.

Maybe move this section below "File and  Directory" and start with something
like

File, Directory and Link all extend FileSystemEntity. In addition to this
FileSystemEntity has a number of static methods for working with paths.

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

Done.

+ * whatever is at that pathname.
+ * Then you can query the FileSystemEntity object to get information
+ * using methods such as 'isDirectory', 'isFile', and 'exists'.
+ * Because file system access can be slow, these methods

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

"can be slow" -> involved I/O.

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

Done.

+ * are asynchronous and return a Future.
+ *
+ *     FileSystemEntity.isDirectory(myPath).then((isDir) {
+ *       if (isDir) {
+ *         print('$myPath is a directory');
+ *       } else {
+ *         print('$myPath is not a directory');
+ *       }
+ *     });
+ *
+ * ## File and Directory

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

Mention Link as well?

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

Done.

+ *
+ * Each instance of [File] or [Directory] represents a file or
+ * directory, respectively, in the native file system.
+ * Both File and Directory are subclasses of FileSystemEntity.
+ * You can manipulate the file system through objects of these types.
+ * 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

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

HttpServer -> HttpServer and HttpClient

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

Done.

+ *

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

The classes [HttpServer] and [HttpClient] provides HTTP server and HTTP client
functionality.

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

Done.

+ * To create an Http server, we recommend that you try using

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

Start with:

The [HttpServer] class provides the basic functionality for implementing an HTTP
server. For some higher-level building-blocks, we recoment ...

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

Done.

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

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

"easy to provide content through HTTP servers" -> "easier to implement HTTP
servers"

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

Done.

+ *

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

Shouldnt we have a sub-section for 

## WebSocket
## Process
## Sockets

To mention we have that. Otherwise people might miss that we support these areas
as well.

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

Thanks. It's great to have a more complete list of important classes in this
library.

On 2013/12/19 09:44:40, Søren Gjesse wrote:

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

Done.

+ * ## 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
+ * (the program blocks waiting for user to type information):
+ *
+ *      String inputText = stdin.readLineSync();
+ *
+ * ## Other resources
+ *
+ * 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/io/).
  */
 library dart.io;