Fix some dart:io documentation comments.

sdk/lib/async/stream.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.
 
 part of dart.async;
 
 // -------------------------------------------------------------------
 // Core Stream types
 // -------------------------------------------------------------------
 
@@ skipping 59 matching lines @@
 
   /**
    * Creates a single-subscription stream that gets its data from [data].
    */
   factory Stream.fromIterable(Iterable<T> data) {
     _PendingEvents iterableEvents = new _IterablePendingEvents<T>(data);
     return new _GeneratedSingleStreamImpl<T>(iterableEvents);
   }
 
   /**
-   * Whether the stream is a broadcast stream.
+   * Reports whether this stream is a broadcast stream.
    */
   bool get isBroadcast => false;
 
   /**
    * Returns a multi-subscription stream that produces the same events as this.
    *
    * If this stream is single-subscription, return a new stream that allows
    * multiple subscribers. It will subscribe to this stream when its first
    * subscriber is added, and unsubscribe again when the last subscription is
    * cancelled.
    *
    * If this stream is already a broadcast stream, it is returned unmodified.
    */
   Stream<T> asBroadcastStream() {
     if (isBroadcast) return this;
     return new _SingleStreamMultiplexer<T>(this);
   }
 
   /**
-   * Add a subscription to this stream.
+   * Adds a subscription to this stream.
    *
-   * On each data event from this stream, the subscribers [onData] handler
+   * On each data event from this stream, the subscriber's [onData] handler
    * is called. If [onData] is null, nothing happens.
    *
    * On errors from this stream, the [onError] handler is given a
    * [AsyncError] object describing the error.
    *
    * If this stream closes, the [onDone] handler is called.
    *
    * If [unsubscribeOnError] is true, the subscription is ended when
    * the first error is reported. The default is false.
    */
   StreamSubscription<T> listen(void onData(T event),
                                { void onError(AsyncError error),
                                  void onDone(),
                                  bool unsubscribeOnError});
 
   /**
    * Creates a new stream from this stream that discards some data events.
    *
    * The new stream sends the same error and done events as this stream,
    * but it only sends the data events that satisfy the [test].
    */
   Stream<T> where(bool test(T event)) {
     return new _WhereStream<T>(this, test);
   }
 
   /**
-   * Create a new stream that converts each element of this stream
+   * Creates a new stream that converts each element of this stream
    * to a new value using the [convert] function.
    */
   Stream map(convert(T event)) {
     return new _MapStream<T, dynamic>(this, convert);
   }
 
   /**
-   * Create a wrapper Stream that intercepts some errors from this stream.
+   * Creates a wrapper Stream that intercepts some errors from this stream.
    *
    * If this stream sends an error that matches [test], then it is intercepted
    * by the [handle] function.
    *
    * An [AsyncError] [:e:] is matched by a test function if [:test(e):] returns
    * true. If [test] is omitted, every error is considered matching.
    *
    * If the error is intercepted, the [handle] function can decide what to do
    * with it. It can throw if it wants to raise a new (or the same) error,
    * or simply return to make the stream forget the error.
    *
    * If you need to transform an error into a data event, use the more generic
    * [Stream.transformEvent] to handle the event by writing a data event to
    * the output sink
    */
   Stream<T> handleError(void handle(AsyncError error), { bool test(error) }) {
     return new _HandleErrorStream<T>(this, handle, test);
   }
 
   /**
-   * Create a new stream from this stream that converts each element
+   * Creates a new stream from this stream that converts each element
    * into zero or more events.
    *
    * Each incoming event is converted to an [Iterable] of new events,
    * and each of these new events are then sent by the returned stream
    * in order.
    */
   Stream expand(Iterable convert(T value)) {
     return new _ExpandStream<T, dynamic>(this, convert);
   }
 
   /**
-   * Bind this stream as the input of the provided [StreamConsumer].
+   * Binds this stream as the input of the provided [StreamConsumer].
    */
   Future pipe(StreamConsumer<T, dynamic> streamConsumer) {
     return streamConsumer.consume(this);
   }
 
   /**
-   * Chain this stream as the input of the provided [StreamTransformer].
+   * Chains this stream as the input of the provided [StreamTransformer].
    *
    * Returns the result of [:streamTransformer.bind:] itself.
    */
   Stream transform(StreamTransformer<T, dynamic> streamTransformer) {
     return streamTransformer.bind(this);
   }
 
   /** Reduces a sequence of values by repeatedly applying [combine]. */
   Future reduce(var initialValue, combine(var previous, T element)) {
     _FutureImpl result = new _FutureImpl();
@@ skipping 30 matching lines @@
         onDone: () {
           sink.close();
           result._setValue(null);
         },
         unsubscribeOnError: unsubscribeOnError);
     return result;
   }
 
 
   /**
-   * Check whether [match] occurs in the elements provided by this stream.
+   * Checks whether [match] occurs in the elements provided by this stream.
    *
    * Completes the [Future] when the answer is known.
    * If this stream reports an error, the [Future] will report that error.
    */
   Future<bool> contains(T match) {
     _FutureImpl<bool> future = new _FutureImpl<bool>();
     StreamSubscription subscription;
     subscription = this.listen(
         // TODO(ahe): Restore type when feature is implemented in dart2js
         // checked mode. http://dartbug.com/7733
@@ skipping 11 matching lines @@
         },
         onError: future._setError,
         onDone: () {
           future._setValue(false);
         },
         unsubscribeOnError: true);
     return future;
   }
 
   /**
-   * Check whether [test] accepts all elements provided by this stream.
+   * Checks whether [test] accepts all elements provided by this stream.
    *
    * Completes the [Future] when the answer is known.
    * If this stream reports an error, the [Future] will report that error.
    */
   Future<bool> every(bool test(T element)) {
     _FutureImpl<bool> future = new _FutureImpl<bool>();
     StreamSubscription subscription;
     subscription = this.listen(
         // TODO(ahe): Restore type when feature is implemented in dart2js
         // checked mode. http://dartbug.com/7733
@@ skipping 11 matching lines @@
         },
         onError: future._setError,
         onDone: () {
           future._setValue(true);
         },
         unsubscribeOnError: true);
     return future;
   }
 
   /**
-   * Check whether [test] accepts any element provided by this stream.
+   * Checks whether [test] accepts any element provided by this stream.
    *
    * Completes the [Future] when the answer is known.
    * If this stream reports an error, the [Future] will report that error.
    */
   Future<bool> any(bool test(T element)) {
     _FutureImpl<bool> future = new _FutureImpl<bool>();
     StreamSubscription subscription;
     subscription = this.listen(
         // TODO(ahe): Restore type when feature is implemented in dart2js
         // checked mode. http://dartbug.com/7733
@@ skipping 130 matching lines @@
         future._setValue(false);
       },
       onError: future._setError,
       onDone: () {
         future._setValue(true);
       },
       unsubscribeOnError: true);
     return future;
   }
 
-  /** Collect the data of this stream in a [List]. */
+  /** Collects the data of this stream in a [List]. */
   Future<List<T>> toList() {
     List<T> result = <T>[];
     _FutureImpl<List<T>> future = new _FutureImpl<List<T>>();
     this.listen(
       // TODO(ahe): Restore type when feature is implemented in dart2js
       // checked mode. http://dartbug.com/7733
       (/*T*/ data) {
         result.add(data);
       },
       onError: future._setError,
       onDone: () {
         future._setValue(result);
       },
       unsubscribeOnError: true);
     return future;
   }
 
-  /** Collect the data of this stream in a [Set]. */
+  /** Collects the data of this stream in a [Set]. */
   Future<Set<T>> toSet() {
     Set<T> result = new Set<T>();
     _FutureImpl<Set<T>> future = new _FutureImpl<Set<T>>();
     this.listen(
       // TODO(ahe): Restore type when feature is implemented in dart2js
       // checked mode. http://dartbug.com/7733
       (/*T*/ data) {
         result.add(data);
       },
       onError: future._setError,
       onDone: () {
         future._setValue(result);
       },
       unsubscribeOnError: true);
     return future;
   }
 
   /**
-   * Provide at most the first [n] values of this stream.
+   * Provides at most the first [n] values of this stream.
    *
    * Forwards the first [n] data events of this stream, and all error
    * events, to the returned stream, and ends with a done event.
    *
    * If this stream produces fewer than [count] values before it's done,
    * so will the returned stream.
    */
   Stream<T> take(int count) {
     return new _TakeStream(this, count);
   }
@@ skipping 23 matching lines @@
    * Error and done events are provided by the returned stream unmodified.
    *
    * Starting with the first data event where [test] returns true for the
    * event data, the returned stream will have the same events as this stream.
    */
   Stream<T> skipWhile(bool test(T value)) {
     return new _SkipWhileStream(this, test);
   }
 
   /**
-   * Skip data events if they are equal to the previous data event.
+   * Skips data events if they are equal to the previous data event.
    *
    * The returned stream provides the same events as this stream, except
    * that it never provides two consequtive data events that are equal.
    *
    * Equality is determined by the provided [equals] method. If that is
    * omitted, the '==' operator on the last provided data element is used.
    */
   Stream<T> distinct([bool equals(T previous, T next)]) {
     return new _DistinctStream(this, equals);
   }
@@ skipping 82 matching lines @@
           future._setValue(result);
           return;
         }
         future._setError(new AsyncError(new StateError("No elements")));
       },
       unsubscribeOnError: true);
     return future;
   }
 
   /**
-   * Find the first element of this stream matching [test].
+   * Finds the first element of this stream matching [test].
    *
    * Returns a future that is filled with the first element of this stream
    * that [test] returns true for.
    *
    * If no such element is found before this stream is done, and a
    * [defaultValue] function is provided, the result of calling [defaultValue]
    * becomes the value of the future.
    *
    * If an error occurs, or if this stream ends without finding a match and
    * with no [defaultValue] function provided, the future will receive an
@@ skipping 466 matching lines @@
 }
 
 class _StreamOutputSinkWrapper<T> implements StreamSink<T> {
   _StreamOutputSink _sink;
   _StreamOutputSinkWrapper(this._sink);
 
   void add(T data) => _sink._sendData(data);
   void signalError(AsyncError error) => _sink._sendError(error);
   void close() => _sink._sendDone();
 }