Update docs on Stream.skip/take/skipWhile/takeWhile.

sdk/lib/async/stream.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 "async.dart";
 
 // -------------------------------------------------------------------
 // Core Stream types
 // -------------------------------------------------------------------
 
@@ skipping 969 matching lines @@
    *
    * In case of a `done` event the future completes with the given
    * [futureValue].
    */
   Future<E> drain<E>([E futureValue]) =>
       listen(null, cancelOnError: true).asFuture<E>(futureValue);
 
   /**
    * Provides at most the first [count] data events of this stream.
    *
-   * Forwards all events of this stream to the returned stream
-   * until [count] data events have been forwarded or this stream ends,
-   * then ends the returned stream with a done event.
+   * Returns a stream that emits the same events that this stream would
+   * if listened to at the same time,
+   * until either this stream ends or it has emitted [count] data events,
+   * at which point the returned stream is done.
    *
    * If this stream produces fewer than [count] data events before it's done,
    * so will the returned stream.
    *
    * Starts listening to this stream when the returned stream is listened to
    * and stops listening when the first [count] data events have been received.
    *
    * This means that if this is a single-subscription (non-broadcast) streams
    * it cannot be reused after the returned stream has been listened to.
    *
    * If this is a broadcast stream, the returned stream is a broadcast stream.
    * In that case, the events are only counted from the time
    * the returned stream is listened to.
    */
   Stream<T> take(int count) {
     return new _TakeStream<T>(this, count);
   }
 
   /**
    * Forwards data events while [test] is successful.
    *
-   * The returned stream provides the same events as this stream as long
-   * as [test] returns `true` for the event data. The stream is done
-   * when either this stream is done, or when this stream first provides
-   * a value that [test] doesn't accept.
+   * Returns a stream that provides the same events as this stream
+   * until [test] fails for a data event.
+   * The returned stream is done when either this stream is done,
+   * or when this stream first emits a data event that fails [test].
    *
-   * Stops listening to the stream after the accepted elements.
+   * The `test` call is considered failing if it returns a non-`true` value
+   * or if it throws. If the `test` call throws, the error is emitted as the
+   * last event on the returned streams.
+   *
+   * Stops listening to this stream after the accepted elements.
    *
    * Internally the method cancels its subscription after these elements. This
    * means that single-subscription (non-broadcast) streams are closed and
    * cannot be reused after a call to this method.
    *
    * The returned stream is a broadcast stream if this stream is.
    * For a broadcast stream, the events are only tested from the time
    * the returned stream is listened to.
    */
   Stream<T> takeWhile(bool test(T element)) {
     return new _TakeWhileStream<T>(this, test);
   }
 
   /**
    * Skips the first [count] data events from this stream.
    *
+   * Returns a stream that emits the same events as this stream would
+   * if listened to at the same time, except that the first [count]
+   * data events are not emitted.
+   * The returned stream is done when this stream is.
+   *
+   * If this stream emits fewer than [count] data events
+   * before being done, the returned stream emits no data events.
+   *
    * The returned stream is a broadcast stream if this stream is.
    * For a broadcast stream, the events are only counted from the time
    * the returned stream is listened to.
    */
   Stream<T> skip(int count) {
     return new _SkipStream<T>(this, count);
   }
 
   /**
    * Skip data events from this stream while they are matched by [test].
    *
+   * Returns a stream that emits the same events as this stream,
+   * except that data events are not emitted until a data event fails `test`.
+   * The test fails when called with a data event
+   * if it returns a non-`true` value or if the call to `test` throws.
+   * If the call throws, the error is emitted as an error event
+   * on the returned stream instead of the data event,
+   * otherwise the event that made `test` return non-true is emitted as the
+   * first data event.
+   *
    * Error and done events are provided by the returned stream unmodified.
    *
-   * Starting with the first data event where [test] returns false for the
-   * event data, the returned stream will have the same events as this stream.
-   *
    * The returned stream is a broadcast stream if this stream is.
    * For a broadcast stream, the events are only tested from the time
    * the returned stream is listened to.
    */
   Stream<T> skipWhile(bool test(T element)) {
     return new _SkipWhileStream<T>(this, test);
   }
 
   /**
    * 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 consecutive data events that are equal.
    * That is, errors are passed through to the returned stream, and
    * data events are passed through if they are distinct from the most
    * recently emitted data event.
    *
    * Equality is determined by the provided [equals] method. If that is
    * omitted, the '==' operator on the last provided data element is used.
    *
    * If [equals] throws, the data event is replaced by an error event
    * containing the thrown error. The behavior is equivalent to the
-   * original stream emitting the error event.
+   * original stream emitting the error event, and it doesn't change
+   * the what the most recently emitted data event is.
    *
    * The returned stream is a broadcast stream if this stream is.
    * If a broadcast stream is listened to more than once, each subscription
    * will individually perform the `equals` test.
    */
   Stream<T> distinct([bool equals(T previous, T next)]) {
     return new _DistinctStream<T>(this, equals);
   }
 
   /**
@@ skipping 289 matching lines @@
               new RangeError.index(index, this, "index", null, elementIndex));
         },
         cancelOnError: true);
     return future;
   }
 
   /**
    * Creates a new stream with the same events as this stream.
    *
    * Whenever more than [timeLimit] passes between two events from this stream,
-   * the [onTimeout] function is called.
+   * the [onTimeout] function is called, which can emit further events on
+   * the returned stream.
    *
    * The countdown doesn't start until the returned stream is listened to.
    * The countdown is reset every time an event is forwarded from this stream,
    * or when the stream is paused and resumed.
    *
    * The [onTimeout] function is called with one argument: an
    * [EventSink] that allows putting events into the returned stream.
-   * This `EventSink` is only valid during the call to `onTimeout`.
+   * This `EventSink` is only valid during the call to [onTimeout].
+   * Calling [EventSink.close] on the sink passed to [onTimeout] closes the
+   * returned stream, and no futher events are processed.
    *
-   * If `onTimeout` is omitted, a timeout will just put a [TimeoutException]
+   * If [onTimeout] is omitted, a timeout will just put a [TimeoutException]
    * into the error channel of the returned stream.
+   * If the call to [onTimeout] throws, the error is emitted on the returned
+   * stream.
    *
    * The returned stream is a broadcast stream if this stream is.
    * If a broadcast stream is listened to more than once, each subscription
    * will have its individually timer that starts counting on listen,
    * and the subscriptions' timers can be paused individually.
    */
   Stream<T> timeout(Duration timeLimit, {void onTimeout(EventSink<T> sink)}) {
     StreamController<T> controller;
     // The following variables are set on listen.
     StreamSubscription<T> subscription;
@@ skipping 584 matching lines @@
   }
 
   void addError(error, [StackTrace stackTrace]) {
     _sink.addError(error, stackTrace);
   }
 
   void close() {
     _sink.close();
   }
 }