Fix documentation in dart:io.

sdk/lib/io/io_sink.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.
 
 part of dart.io;
 
 /**
  * Helper class to wrap a [StreamConsumer<List<int>>] and provide
  * utility functions for writing to the StreamConsumer directly. The
  * [IOSink] buffers the input given by all [StringSink] methods and will delay
  * a [addStream] until the buffer is flushed.

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

a -> an

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

  *
  * When the [IOSink] is bound to a stream (through [addStream]) any call
  * to the [IOSink] will throw a [StateError]. When the [addStream] completes,
  * the [IOSink] will again be open for all calls.
  *
  * If data is added to the [IOSink] after the sink is closed, the data will be
  * ignored. Use the [done] future to be notified when the [IOSink] is closed.
  */
 abstract class IOSink implements StreamSink<List<int>>, StringSink {
   factory IOSink(StreamConsumer<List<int>> target,
                  {Encoding encoding: UTF8})
       => new _IOSinkImpl(target, encoding);
 
   /**
    * The [Encoding] used when writing strings. Depending on the
    * underlying consumer this property might be mutable.

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

Make it a getter here, and add a setter only where it is mutable?

[Anders Johnsen, 2014/03/18 12:30:57]

No, can't do :)

    */
   Encoding encoding;
 
   /**
-   * Writes the bytes uninterpreted to the consumer. While the call is
-   * synchronous, the data may be buffered until the underlying resource is
-   * ready. The data should not be modified after a call to [add].
+   * Writes the bytes uninterpreted to the consumer.

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

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.

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

+   *
+   * This function can not be called, when a stream is currently being added by

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

can not -> must not
remove comma
added by -> added using

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

+   * [addStream].
+   *
+   * This operation is non-blocking. See [flush] or [done] for how to get any
+   * errors that this call may have generated. The data should not be modified

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

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`.

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

+   * after a call to [add].
    */
   void add(List<int> data);
 
   /**
+   * Converts [obj] to a String by invoking [Object.toString] and
+   * [add]s the result to the consumer.

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

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).

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

+   *
+   * This operation is non-blocking. See [flush] or [done] for how to get any
+   * errors that this call may have generated.
+   */
+  void write(Object obj);
+
+  /**
+   * Iterates over the given [objects] and [write]s them in sequence.

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

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

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

+   *
+   * This operation is non-blocking. See [flush] or [done] for how to get any
+   * errors that this call may have generated.
+   */
+  void writeAll(Iterable objects, [String separator = ""]);
+
+  /**
+   * Converts [obj] to a String by invoking [Object.toString] and
+   * adds the result to `this`, followed by a newline.

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

adds -> writes

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

+   *
+   * This operation is non-blocking. See [flush] or [done] for how to get any
+   * errors that this call may have generated.
+   */
+  void writeln([Object obj = ""]);
+
+  /**
+   * Writes the [charCode] to `this`.
+   *
+   * This method is equivalent to `write(new String.fromCharCode(charCode))`.
+   *
+   * This operation is non-blocking. See [flush] or [done] for how to get any
+   * errors that this call may have generated.
+   */
+  void writeCharCode(int charCode);
+
+  /**
    * Writes an error to the consumer.

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

Passes the error to the target consumer as an error event.

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

+   *
+   * This function can not be called, when a stream is currently being added by

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

can not -> must not
remove comma.
added by -> added using

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

+   * [addStream].
+   *
+   * This operation is non-blocking. See [flush] or [done] for how to get any
+   * errors that this call may have generated.
    */
   void addError(error, [StackTrace stackTrace]);
 
   /**
    * Adds all elements of the given [stream] to `this`.
    */
   Future addStream(Stream<List<int>> stream);
 
   /**
    * Returns a [Future] that completes once all buffered data is accepted by the
    * to underlying [StreamConsumer].
    *
    * It's an error to call this method, while an [addStream] is incomplete.
    *
    * NOTE: This is not necessarily the same as the data being flushed by the
    * operating system.
    */
   Future flush();
 
   /**
-   * Close the target.
+   * Close the consumer.

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

Close the target consumer.

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

    */
   Future close();
 
   /**
-   * Get a future that will complete when all synchronous have completed, or an
-   * error happened. This future is identical to the future returned from close.
+   * Get a future that will complete when the consumer is closed, or an

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

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).

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

+   * error happened. This future is identical to the future returned from

[Lasse Reichstein Nielsen, 2014/03/18 11:57:14]

returned from -> returned by.

[Anders Johnsen, 2014/03/18 12:30:57]

Done.

+   * [close].
    */
   Future get done;
 }
 
 class _StreamSinkImpl<T> implements StreamSink<T> {
   final StreamConsumer<T> _target;
   Completer _doneCompleter = new Completer();
   Future _doneFuture;
   StreamController<T> _controllerInstance;
   Completer _controllerCompleter;
@@ skipping 173 matching lines @@
 
   void writeln([Object obj = ""]) {
     write(obj);
     write("\n");
   }
 
   void writeCharCode(int charCode) {
     write(new String.fromCharCode(charCode));
   }
 }