Fix documentation in dart:io.

Fix documentation in dart:io.

BUG=https://code.google.com/p/dart/issues/detail?id=17365,https://code.google.com/p/dart/issues/detail?id=17359,https://code.google.com/p/dart/issues/detail?id=17355,https://code.google.com/p/dart/issues/detail?id=16144
R=lrn@google.com, sgjesse@google.com

Committed: https://code.google.com/p/dart/source/detail?r=33801

[Søren Gjesse, 2014-03-18 11:15:46]

lgtm

[Lasse Reichstein Nielsen, 2014-03-18 11:57:13]

lgtm

https://codereview.chromium.org/203263003/diff/1/sdk/lib/async/async.dart
File sdk/lib/async/async.dart (right):

https://codereview.chromium.org/203263003/diff/1/sdk/lib/async/async.dart#new...
sdk/lib/async/async.dart:47: * such as mouse clicks, and a stream of byte lists
read from a file.
How about:
... include individual events, like mouse clicks, or sequential chunks of larger
data, like byte lists with the contents of a file.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/http.dart
File sdk/lib/io/http.dart (right):

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/http.dart#newcode756
sdk/lib/io/http.dart:756: * An HttpRequest object delivers the body content of
the request
Isn't it the body of the response, not the request?

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/http.dart#newcode756
sdk/lib/io/http.dart:756: * An HttpRequest object delivers the body content of
the request
`HttpRequest` everywhere.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart
File sdk/lib/io/io_sink.dart (right):

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:11: * a [addStream] until the buffer is flushed.
a -> an

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:27: * underlying consumer this property might be
mutable.
Make it a getter here, and add a setter only where it is mutable?

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:32: * Writes the bytes uninterpreted to the consumer.
Adds [data] to the target consumer, ignoring [encoding].

The encoding does not apply to this method, and the `data` list is passed
directly to the target consumer as a stream event.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:34: * This function can not be called, when a stream is
currently being added by
can not -> must not
remove comma
added by -> added using

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:38: * errors that this call may have generated. The data
should not be modified
that this call may have generated -> generated by this call.
(dittos below)

The data list should not be modified after it has been passed to `add`.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:45: * [add]s the result to the consumer.
adds the result -> adds the encoding of the result to the target consumer.
(Or some other way of mentioning that the string is encoded into bytes).

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:53: * Iterates over the given [objects] and [write]s
them in sequence.

If [separator] is provided, a `write` with the `separator` is performed between
any two elements of `objects`.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:62: * adds the result to `this`, followed by a newline.
adds -> writes

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:80: * Writes an error to the consumer.
Passes the error to the target consumer as an error event.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:82: * This function can not be called, when a stream is
currently being added by
can not -> must not
remove comma.
added by -> added using

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:107: * Close the consumer.
Close the target consumer.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:112: * Get a future that will complete when the consumer
is closed, or an
is closed -> closes
or an error happened -> or when an error occurs.
(will complete means future, so don't use past tense about the conditions).

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:113: * error happened. This future is identical to the
future returned from
returned from -> returned by.

[Anders Johnsen, 2014-03-18 12:30:56]

https://codereview.chromium.org/203263003/diff/1/sdk/lib/async/async.dart
File sdk/lib/async/async.dart (right):

https://codereview.chromium.org/203263003/diff/1/sdk/lib/async/async.dart#new...
sdk/lib/async/async.dart:47: * such as mouse clicks, and a stream of byte lists
read from a file.
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> How about:
> ... include individual events, like mouse clicks, or sequential chunks of
larger
> data, like byte lists with the contents of a file.

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/http.dart
File sdk/lib/io/http.dart (right):

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/http.dart#newcode756
sdk/lib/io/http.dart:756: * An HttpRequest object delivers the body content of
the request
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> Isn't it the body of the response, not the request?

Nope, think POST requests.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/http.dart#newcode756
sdk/lib/io/http.dart:756: * An HttpRequest object delivers the body content of
the request
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> `HttpRequest` everywhere.

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart
File sdk/lib/io/io_sink.dart (right):

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:11: * a [addStream] until the buffer is flushed.
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> a -> an

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:27: * underlying consumer this property might be
mutable.
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> Make it a getter here, and add a setter only where it is mutable?

No, can't do :)

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:32: * Writes the bytes uninterpreted to the consumer.
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> Adds [data] to the target consumer, ignoring [encoding].
> 
> The encoding does not apply to this method, and the `data` list is passed
> directly to the target consumer as a stream event.

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:34: * This function can not be called, when a stream is
currently being added by
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> can not -> must not
> remove comma
> added by -> added using

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:38: * errors that this call may have generated. The data
should not be modified
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> that this call may have generated -> generated by this call.
> (dittos below)
> 
> The data list should not be modified after it has been passed to `add`.

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:45: * [add]s the result to the consumer.
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> adds the result -> adds the encoding of the result to the target consumer.
> (Or some other way of mentioning that the string is encoded into bytes).

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:53: * Iterates over the given [objects] and [write]s
them in sequence.
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> 
> If [separator] is provided, a `write` with the `separator` is performed
between
> any two elements of `objects`.

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:62: * adds the result to `this`, followed by a newline.
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> adds -> writes

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:80: * Writes an error to the consumer.
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> Passes the error to the target consumer as an error event.

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:82: * This function can not be called, when a stream is
currently being added by
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> can not -> must not
> remove comma.
> added by -> added using

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:107: * Close the consumer.
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> Close the target consumer.

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:112: * Get a future that will complete when the consumer
is closed, or an
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> is closed -> closes
> or an error happened -> or when an error occurs.
> (will complete means future, so don't use past tense about the conditions).

Done.

https://codereview.chromium.org/203263003/diff/1/sdk/lib/io/io_sink.dart#newc...
sdk/lib/io/io_sink.dart:113: * error happened. This future is identical to the
future returned from
On 2014/03/18 11:57:14, Lasse Reichstein Nielsen wrote:
> returned from -> returned by.

Done.

[Anders Johnsen, 2014-03-18 12:31:02]

Committed patchset #2 manually as r33801 (presubmit successful).