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 [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;
 
 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';