Rephrase "Returns a stream" docs (dart-lang/stream_transform#149)
Following up on a recent PR comment about this phrasing in the docs for
`buffer` and `sample`. Rewrite all doc headers that started with
"Returns a stream" to instead focus on the action on the stream.
Reference `debounce` and `audit` from the `throttle` docs.
Move the paragraphs with comparisons to `throttle` and `debounce` to a
"See also" section in the `audit` docs.
Replace some "the original stream" and "the source stream" with "this
stream".
Where some comments had to reflow anyway, separate sentences onto their
own lines to reduce churn in the future in any sentence changes.
Remove some unnecessary `Stream.` prefixes in dartdoc references.
diff --git a/pkgs/stream_transform/lib/src/async_expand.dart b/pkgs/stream_transform/lib/src/async_expand.dart
index 265f481..98d8bb7 100644
--- a/pkgs/stream_transform/lib/src/async_expand.dart
+++ b/pkgs/stream_transform/lib/src/async_expand.dart
@@ -18,7 +18,7 @@
/// before the [Stream] emitted by the previous element has closed.
///
/// Events on the result stream will be emitted in the order they are emitted
- /// by the sub streams, which may not match the order of the original stream.
+ /// by the sub streams, which may not match the order of this stream.
///
/// Errors from [convert], the source stream, or any of the sub streams are
/// forwarded to the result stream.
@@ -37,9 +37,8 @@
/// back.
///
/// See also:
- ///
- /// * [switchMap], which cancels subscriptions to the previous sub
- /// stream instead of concurrently emitting events from all sub streams.
+ /// - [switchMap], which cancels subscriptions to the previous sub stream
+ /// instead of concurrently emitting events from all sub streams.
Stream<S> concurrentAsyncExpand<S>(Stream<S> Function(T) convert) {
final controller = isBroadcast
? StreamController<S>.broadcast(sync: true)
diff --git a/pkgs/stream_transform/lib/src/async_map.dart b/pkgs/stream_transform/lib/src/async_map.dart
index c789827..c2ea253 100644
--- a/pkgs/stream_transform/lib/src/async_map.dart
+++ b/pkgs/stream_transform/lib/src/async_map.dart
@@ -22,21 +22,22 @@
/// Like [asyncMap] but events are buffered until previous events have been
/// processed by [convert].
///
- /// If the source stream is a broadcast stream the result will be as well. When
- /// used with a broadcast stream behavior also differs from [Stream.asyncMap] in
- /// that the [convert] function is only called once per event, rather than once
- /// per listener per event.
+ /// If this stream is a broadcast stream the result will be as well.
+ /// When used with a broadcast stream behavior also differs from [asyncMap] in
+ /// that the [convert] function is only called once per event, rather than
+ /// once per listener per event.
///
- /// The first event from the source stream is always passed to [convert] as a
- /// List with a single element. After that events are buffered until the
- /// previous Future returned from [convert] has fired.
+ /// The first event from this stream is always passed to [convert] as a
+ /// list with a single element.
+ /// After that, events are buffered until the previous Future returned from
+ /// [convert] has completed.
///
- /// Errors from the source stream are forwarded directly to the result stream.
+ /// Errors from this stream are forwarded directly to the result stream.
/// Errors during the conversion are also forwarded to the result stream and
/// are considered completing work so the next values are let through.
///
- /// The result stream will not close until the source stream closes and all
- /// pending conversions have finished.
+ /// The result stream will not close until this stream closes and all pending
+ /// conversions have finished.
Stream<S> asyncMapBuffer<S>(Future<S> Function(List<T>) convert) {
var workFinished = StreamController<void>()
// Let the first event through.
@@ -47,22 +48,22 @@
/// Like [asyncMap] but events are discarded while work is happening in
/// [convert].
///
- /// If the source stream is a broadcast stream the result will be as well. When
- /// used with a broadcast stream behavior also differs from [Stream.asyncMap] in
- /// that the [convert] function is only called once per event, rather than once
- /// per listener per event.
+ /// If this stream is a broadcast stream the result will be as well.
+ /// When used with a broadcast stream behavior also differs from [asyncMap] in
+ /// that the [convert] function is only called once per event, rather than
+ /// once per listener per event.
///
/// If no work is happening when an event is emitted it will be immediately
/// passed to [convert]. If there is ongoing work when an event is emitted it
/// will be held until the work is finished. New events emitted will replace a
/// pending event.
///
- /// Errors from the source stream are forwarded directly to the result stream.
+ /// Errors from this stream are forwarded directly to the result stream.
/// Errors during the conversion are also forwarded to the result stream and are
/// considered completing work so the next values are let through.
///
- /// The result stream will not close until the source stream closes and all
- /// pending conversions have finished.
+ /// The result stream will not close until this stream closes and all pending
+ /// conversions have finished.
Stream<S> asyncMapSample<S>(Future<S> Function(T) convert) {
var workFinished = StreamController<void>()
// Let the first event through.
@@ -79,19 +80,19 @@
/// before processing for the previous element is finished.
///
/// Events on the result stream will be emitted in the order that [convert]
- /// completed which may not match the order of the original stream.
+ /// completed which may not match the order of this stream.
///
- /// If the source stream is a broadcast stream the result will be as well.
+ /// If this stream is a broadcast stream the result will be as well.
/// When used with a broadcast stream behavior also differs from [asyncMap] in
/// that the [convert] function is only called once per event, rather than
/// once per listener per event. The [convert] callback won't be called for
/// events while a broadcast stream has no listener.
///
- /// Errors from [convert] or the source stream are forwarded directly to the
+ /// Errors from [convert] or this stream are forwarded directly to the
/// result stream.
///
- /// The result stream will not close until the source stream closes and all
- /// pending conversions have finished.
+ /// The result stream will not close until this stream closes and all pending
+ /// conversions have finished.
Stream<S> concurrentAsyncMap<S>(FutureOr<S> Function(T) convert) {
var valuesWaiting = 0;
var sourceDone = false;
diff --git a/pkgs/stream_transform/lib/src/combine_latest.dart b/pkgs/stream_transform/lib/src/combine_latest.dart
index dcaf672..5fbdbf5 100644
--- a/pkgs/stream_transform/lib/src/combine_latest.dart
+++ b/pkgs/stream_transform/lib/src/combine_latest.dart
@@ -7,8 +7,8 @@
/// Utilities to combine events from multiple streams through a callback or into
/// a list.
extension CombineLatest<T> on Stream<T> {
- /// Returns a stream which combines the latest value from the source stream
- /// with the latest value from [other] using [combine].
+ /// Combines the latest values from this stream with the latest values from
+ /// [other] using [combine].
///
/// No event will be emitted until both the source stream and [other] have
/// each emitted at least one event. If either the source stream or [other]
diff --git a/pkgs/stream_transform/lib/src/concatenate.dart b/pkgs/stream_transform/lib/src/concatenate.dart
index 37a4d96..3277dcd 100644
--- a/pkgs/stream_transform/lib/src/concatenate.dart
+++ b/pkgs/stream_transform/lib/src/concatenate.dart
@@ -6,21 +6,21 @@
/// Utilities to append or prepend to a stream.
extension Concatenate<T> on Stream<T> {
- /// Returns a stream which emits values and errors from [next] after the
- /// original stream is complete.
+ /// Emits all values and errors from [next] following all values and errors
+ /// from this stream.
///
- /// If the source stream never finishes, the [next] stream will never be
- /// listened to.
+ /// If this stream never finishes, the [next] stream will never get a
+ /// listener.
///
- /// If the source stream is a broadcast stream, the result will be as well.
+ /// If this stream is a broadcast stream, the result will be as well.
/// If a single-subscription follows a broadcast stream it may be listened
/// to and never canceled since there may be broadcast listeners added later.
///
/// If a broadcast stream follows any other stream it will miss any events or
- /// errors which occur before the original stream is done. If a broadcast
- /// stream follows a single-subscription stream, pausing the stream while it
- /// is listening to the second stream will cause events to be dropped rather
- /// than buffered.
+ /// errors which occur before this stream is done.
+ /// If a broadcast stream follows a single-subscription stream, pausing the
+ /// stream while it is listening to the second stream will cause events to be
+ /// dropped rather than buffered.
Stream<T> followedBy(Stream<T> next) {
var controller = isBroadcast
? StreamController<T>.broadcast(sync: true)
@@ -79,28 +79,27 @@
return controller.stream;
}
- /// Returns a stream which emits [initial] before any values from the original
- /// stream.
+ /// Emits [initial] before any values or errors from the this stream.
///
- /// If the original stream is a broadcast stream the result will be as well.
+ /// If this stream is a broadcast stream the result will be as well.
Stream<T> startWith(T initial) =>
startWithStream(Future.value(initial).asStream());
- /// Returns a stream which emits all values in [initial] before any values
- /// from the original stream.
+ /// Emits all values in [initial] before any values or errors from this
+ /// stream.
///
- /// If the original stream is a broadcast stream the result will be as well.
- /// If the original stream is a broadcast stream it will miss any events which
+ /// If this stream is a broadcast stream the result will be as well.
+ /// If this stream is a broadcast stream it will miss any events which
/// occur before the initial values are all emitted.
Stream<T> startWithMany(Iterable<T> initial) =>
startWithStream(Stream.fromIterable(initial));
- /// Returns a stream which emits all values in [initial] before any values
- /// from the original stream.
+ /// Emits all values and errors in [initial] before any values or errors from
+ /// this stream.
///
- /// If the original stream is a broadcast stream the result will be as well. If
- /// the original stream is a broadcast stream it will miss any events which
- /// occur before [initial] closes.
+ /// If this stream is a broadcast stream the result will be as well.
+ /// If this stream is a broadcast stream it will miss any events which occur
+ /// before [initial] closes.
Stream<T> startWithStream(Stream<T> initial) {
if (isBroadcast && !initial.isBroadcast) {
initial = initial.asBroadcastStream();
diff --git a/pkgs/stream_transform/lib/src/merge.dart b/pkgs/stream_transform/lib/src/merge.dart
index 7784bdb..2725d5e 100644
--- a/pkgs/stream_transform/lib/src/merge.dart
+++ b/pkgs/stream_transform/lib/src/merge.dart
@@ -6,11 +6,11 @@
/// Utilities to interleave events from multiple streams.
extension Merge<T> on Stream<T> {
- /// Returns a stream which emits values and errors from the source stream and
- /// [other] in any order as they arrive.
+ /// Merges values and errors from this stream and [other] in any order as they
+ /// arrive.
///
- /// The result stream will not close until both the source stream and [other]
- /// have closed.
+ /// The result stream will not close until both this stream and [other] have
+ /// closed.
///
/// For example:
///
@@ -20,7 +20,7 @@
/// other: ------4-------5--|
/// result: 1--2--4--3----5--|
///
- /// If the source stream is a broadcast stream, the result stream will be as
+ /// If this stream is a broadcast stream, the result stream will be as
/// well, regardless of [other]'s type. If a single subscription stream is
/// merged into a broadcast stream it may never be canceled since there may be
/// broadcast listeners added later.
@@ -30,10 +30,10 @@
/// be discarded.
Stream<T> merge(Stream<T> other) => mergeAll([other]);
- /// Returns a stream which emits values and errors from the source stream and
- /// any stream in [others] in any order as they arrive.
+ /// Merges values and errors from this stream and any stream in [others] in
+ /// any order as they arrive.
///
- /// The result stream will not close until the source stream and all streams
+ /// The result stream will not close until this stream and all streams
/// in [others] have closed.
///
/// For example:
@@ -45,7 +45,7 @@
/// third: ------6---------------7--|
/// result: 1--2--6--4--3----5----7--|
///
- /// If the source stream is a broadcast stream, the result stream will be as
+ /// If this stream is a broadcast stream, the result stream will be as
/// well, regardless the types of streams in [others]. If a single
/// subscription stream is merged into a broadcast stream it may never be
/// canceled since there may be broadcast listeners added later.
diff --git a/pkgs/stream_transform/lib/src/rate_limit.dart b/pkgs/stream_transform/lib/src/rate_limit.dart
index 1d31339..347919b 100644
--- a/pkgs/stream_transform/lib/src/rate_limit.dart
+++ b/pkgs/stream_transform/lib/src/rate_limit.dart
@@ -17,8 +17,7 @@
/// - [audit] - emit the _last_ event at the _end_ of the period.
/// - [buffer] - emit _all_ events on a _trigger_.
extension RateLimit<T> on Stream<T> {
- /// Returns a Stream which suppresses events with less inter-event spacing
- /// than [duration].
+ /// Suppresses events with less inter-event spacing than [duration].
///
/// Events which are emitted with less than [duration] elapsed between them
/// are considered to be part of the same "series". If [leading] is `true`,
@@ -28,13 +27,13 @@
/// must be specified with `leading: true, trailing: false` to emit only
/// leading events.
///
- /// If the source stream is a broadcast stream, the result will be as well.
+ /// If this stream is a broadcast stream, the result will be as well.
/// Errors are forwarded immediately.
///
/// If there is a trailing event waiting during the debounce period when the
/// source stream closes the returned stream will wait to emit it following
/// the debounce period before closing. If there is no pending debounced event
- /// when the source stream closes the returned stream will close immediately.
+ /// when this stream closes the returned stream will close immediately.
///
/// For example:
///
@@ -59,47 +58,49 @@
_debounceAggregate(duration, _dropPrevious,
leading: leading, trailing: trailing);
- /// Returns a Stream which collects values until the source stream does not
- /// emit for [duration] then emits the collected values.
+ /// Buffers values until this stream does not emit for [duration] then emits
+ /// the collected values.
///
/// Values will always be delayed by at least [duration], and values which
/// come within this time will be aggregated into the same list.
///
- /// If the source stream is a broadcast stream, the result will be as well.
+ /// If this stream is a broadcast stream, the result will be as well.
/// Errors are forwarded immediately.
///
- /// If there are events waiting during the debounce period when the source
- /// stream closes the returned stream will wait to emit them following the
- /// debounce period before closing. If there are no pending debounced events
- /// when the source stream closes the returned stream will close immediately.
+ /// If there are events waiting during the debounce period when this stream
+ /// closes the returned stream will wait to emit them following the debounce
+ /// period before closing. If there are no pending debounced events when this
+ /// stream closes the returned stream will close immediately.
///
/// To keep only the most recent event during the debounce period see
/// [debounce].
Stream<List<T>> debounceBuffer(Duration duration) =>
_debounceAggregate(duration, _collect, leading: false, trailing: true);
- /// Returns a stream which only emits once per [duration], at the beginning of
- /// the period.
+ /// Reduces the rate that events are emitted to at most once per [duration].
///
/// No events will ever be emitted within [duration] of another event on the
/// result stream.
- /// If the source stream is a broadcast stream, the result will be as well.
+ /// If this stream is a broadcast stream, the result will be as well.
/// Errors are forwarded immediately.
///
/// If [trailing] is `false`, source events emitted during the [duration]
- /// period following a result event are discarded. The result stream will not
- /// emit an event until the source stream emits an event following the
- /// throttled period. If the source stream is consistently emitting events
- /// with less than [duration] between events, the time between events on the
- /// result stream may still be more than [duration]. The result stream will
- /// close immediately when the source stream closes.
+ /// period following a result event are discarded.
+ /// The result stream will not emit an event until this stream emits an event
+ /// following the throttled period.
+ /// If this stream is consistently emitting events with less than
+ /// [duration] between events, the time between events on the result stream
+ /// may still be more than [duration].
+ /// The result stream will close immediately when this stream closes.
///
/// If [trailing] is `true`, the latest source event emitted during the
/// [duration] period following an result event is held and emitted following
- /// the period. If the source stream is consistently emitting events with less
- /// than [duration] between events, the time between events on the result
- /// stream will be [duration]. If the source stream closes the result stream
- /// will wait to emit a pending event before closing.
+ /// the period.
+ /// If this stream is consistently emitting events with less than [duration]
+ /// between events, the time between events on the result stream will be
+ /// [duration].
+ /// If this stream closes the result stream will wait to emit a pending event
+ /// before closing.
///
/// For example:
///
@@ -117,6 +118,14 @@
///
/// source: 1-2-----------3|
/// result: 1-----2-------3|
+ ///
+ /// See also:
+ /// - [audit], which emits the most recent event at the end of the period.
+ /// Compared to `audit`, `throttle` will not introduce delay to forwarded
+ /// elements, except for the [trailing] events.
+ /// - [debounce], which uses inter-event spacing instead of a fixed period
+ /// from the first event in a window. Compared to `debouce`, `throttle` cannot
+ /// be starved by having events emitted continuously within [duration].
Stream<T> throttle(Duration duration, {bool trailing = false}) =>
trailing ? _throttleTrailing(duration) : _throttle(duration);
@@ -171,33 +180,40 @@
});
}
- /// Returns a Stream which only emits once per [duration], at the end of the
- /// period.
+ /// Audit a single event from each [duration] length period where there are
+ /// events on this stream.
///
- /// If the source stream is a broadcast stream, the result will be as well.
+ /// No events will ever be emitted within [duration] of another event on the
+ /// result stream.
+ /// If this stream is a broadcast stream, the result will be as well.
/// Errors are forwarded immediately.
///
- /// If there is no pending event when the source stream closes the output
+ /// The first event will begin the audit period. At the end of the audit
+ /// period the most recent event is emitted, and the next event restarts the
+ /// audit period.
+ ///
+ /// If the event that started the period is the one that is emitted it will be
+ /// delayed by [duration]. If a later event comes in within the period it's
+ /// delay will be shorter by the difference in arrival times.
+ ///
+ /// If there is no pending event when this stream closes the output
/// stream will close immediately. If there is a pending event the output
/// stream will wait to emit it before closing.
///
- /// Differs from `throttle` in that it always emits the most recently received
- /// event rather than the first in the period. The events that are emitted are
- /// always delayed by some amount. If the event that started the period is the
- /// one that is emitted it will be delayed by [duration]. If a later event
- /// comes in within the period it's delay will be shorter by the difference in
- /// arrival times.
- ///
- /// Differs from `debounce` in that a value will always be emitted after
- /// [duration], the output will not be starved by values coming in repeatedly
- /// within [duration].
- ///
/// For example:
///
/// source.audit(Duration(seconds: 5));
///
/// source: a------b--c----d--|
/// output: -----a------c--------d|
+ ///
+ /// See also:
+ /// - [throttle], which emits the _first_ event during the window, instead of
+ /// the last event in the window. Compared to `throttle`, `audit` will
+ /// introduce delay to forwarded events.
+ /// - [debounce], which only emits after the stream has not emitted for some
+ /// period. Compared to `debouce`, `audit` cannot be starved by having events
+ /// emitted continuously within [duration].
Stream<T> audit(Duration duration) {
Timer? timer;
var shouldClose = false;
@@ -236,12 +252,12 @@
/// The result stream will close as soon as there is a guarantee it will not
/// emit any more events. There will not be any more events emitted if:
/// - [trigger] is closed and there is no waiting long poll.
- /// - Or, the source stream is closed and previously buffered events have been
+ /// - Or, this stream is closed and previously buffered events have been
/// delivered.
///
- /// If the source stream is a broadcast stream, the result will be as well.
- /// Errors from the source stream or the trigger are immediately forwarded to
- /// the output.
+ /// If this stream is a broadcast stream, the result will be as well.
+ /// Errors from this stream or the trigger are immediately forwarded to the
+ /// output.
///
/// See also:
/// - [sample] which use a [trigger] stream in the same way, but keeps only
@@ -253,8 +269,8 @@
longPoll: longPoll,
onEmpty: _empty);
- /// Creates a stream which emits the most recent new value from the source
- /// stream when it sees a value on [trigger].
+ /// Emits the most recent new value from this stream when [trigger] emits an
+ /// event.
///
/// If [longPoll] is `false`, then an event on [trigger] when there is no
/// pending source event will be ignored.
@@ -274,11 +290,11 @@
/// The result stream will close as soon as there is a guarantee it will not
/// emit any more events. There will not be any more events emitted if:
/// - [trigger] is closed and there is no waiting long poll.
- /// - Or, the source stream is closed and any pending source event has been
+ /// - Or, this source stream is closed and any pending source event has been
/// delivered.
///
- /// If the source stream is a broadcast stream, the result will be as well.
- /// Errors from the source stream or the trigger are immediately forwarded to
+ /// If this source stream is a broadcast stream, the result will be as well.
+ /// Errors from this source stream or the trigger are immediately forwarded to
/// the output.
///
/// See also:
@@ -291,7 +307,7 @@
longPoll: longPoll,
onEmpty: _ignore);
- /// Aggregates values until the source stream does not emit for [duration],
+ /// Aggregates values until this source stream does not emit for [duration],
/// then emits the aggregated values.
Stream<S> _debounceAggregate<S>(
Duration duration, S Function(T element, S? soFar) collect,
diff --git a/pkgs/stream_transform/lib/src/scan.dart b/pkgs/stream_transform/lib/src/scan.dart
index d14381c..acd3c76 100644
--- a/pkgs/stream_transform/lib/src/scan.dart
+++ b/pkgs/stream_transform/lib/src/scan.dart
@@ -6,13 +6,16 @@
/// A utility similar to [fold] which emits intermediate accumulations.
extension Scan<T> on Stream<T> {
- /// Like [fold], but instead of producing a single value it yields each
- /// intermediate accumulation.
+ /// Emits a sequence of the accumulated values from repeatedly applying
+ /// [combine].
///
- /// If [combine] returns a Future it will not be called again for subsequent
+ /// Like [fold], but instead of producing a single value it yields each
+ /// intermediate result.
+ ///
+ /// If [combine] returns a future it will not be called again for subsequent
/// events from the source until it completes, therefore [combine] is always
/// called for elements in order, and the result stream always maintains the
- /// same order as the original.
+ /// same order as this stream.
Stream<S> scan<S>(
S initialValue, FutureOr<S> Function(S soFar, T element) combine) {
var accumulated = initialValue;
diff --git a/pkgs/stream_transform/lib/src/switch.dart b/pkgs/stream_transform/lib/src/switch.dart
index c749fbf..4b4cdac 100644
--- a/pkgs/stream_transform/lib/src/switch.dart
+++ b/pkgs/stream_transform/lib/src/switch.dart
@@ -35,8 +35,7 @@
/// and never canceled.
///
/// See also:
- ///
- /// * [concurrentAsyncExpand], which emits events from all sub streams
+ /// - [concurrentAsyncExpand], which emits events from all sub streams
/// concurrently instead of cancelling subscriptions to previous subs streams.
Stream<S> switchMap<S>(Stream<S> Function(T) convert) {
return map(convert).switchLatest();
diff --git a/pkgs/stream_transform/lib/src/take_until.dart b/pkgs/stream_transform/lib/src/take_until.dart
index 32366ed..8f63d94 100644
--- a/pkgs/stream_transform/lib/src/take_until.dart
+++ b/pkgs/stream_transform/lib/src/take_until.dart
@@ -6,8 +6,8 @@
/// A utility to end a stream based on an external trigger.
extension TakeUntil<T> on Stream<T> {
- /// Returns a stream which emits values from the source stream until [trigger]
- /// fires.
+ /// Takes values from this stream which are emitted before [trigger]
+ /// completes.
///
/// Completing [trigger] differs from canceling a subscription in that values
/// which are emitted before the trigger, but have further asynchronous delays
diff --git a/pkgs/stream_transform/lib/src/tap.dart b/pkgs/stream_transform/lib/src/tap.dart
index 05ab32f..4b16ab5 100644
--- a/pkgs/stream_transform/lib/src/tap.dart
+++ b/pkgs/stream_transform/lib/src/tap.dart
@@ -8,15 +8,15 @@
/// Taps into this stream to allow additional handling on a single-subscriber
/// stream without first wrapping as a broadcast stream.
///
- /// The [onValue] callback will be called with every value from the source
- /// stream before it is forwarded to listeners on the resulting stream. May be
- /// null if only [onError] or [onDone] callbacks are needed.
+ /// The [onValue] callback will be called with every value from this stream
+ /// before it is forwarded to listeners on the resulting stream.
+ /// May be null if only [onError] or [onDone] callbacks are needed.
///
- /// The [onError] callback will be called with every error from the source
- /// stream before it is forwarded to listeners on the resulting stream.
+ /// The [onError] callback will be called with every error from this stream
+ /// before it is forwarded to listeners on the resulting stream.
///
- /// The [onDone] callback will be called after the source stream closes and
- /// before the resulting stream is closed.
+ /// The [onDone] callback will be called after this stream closes and before
+ /// the resulting stream is closed.
///
/// Errors from any of the callbacks are caught and ignored.
///
diff --git a/pkgs/stream_transform/lib/src/where.dart b/pkgs/stream_transform/lib/src/where.dart
index ed3532e..569dc31 100644
--- a/pkgs/stream_transform/lib/src/where.dart
+++ b/pkgs/stream_transform/lib/src/where.dart
@@ -8,7 +8,7 @@
/// Utilities to filter events.
extension Where<T> on Stream<T> {
- /// Returns a stream which emits only the events which have type [S].
+ /// Discards events from this stream that are not of type [S].
///
/// If the source stream is a broadcast stream the result will be as well.
///
@@ -21,15 +21,17 @@
if (event is S) sink.add(event);
});
+ /// Discards events from this stream based on an asynchronous [test] callback.
+ ///
/// Like [where] but allows the [test] to return a [Future].
///
/// Events on the result stream will be emitted in the order that [test]
- /// completes which may not match the order of the original stream.
+ /// completes which may not match the order of this stream.
///
/// If the source stream is a broadcast stream the result will be as well. When
- /// used with a broadcast stream behavior also differs from [Stream.where] in
- /// that the [test] function is only called once per event, rather than once
- /// per listener per event.
+ /// used with a broadcast stream behavior also differs from [where] in that
+ /// the [test] function is only called once per event, rather than once per
+ /// listener per event.
///
/// Errors from the source stream are forwarded directly to the result stream.
/// Errors from [test] are also forwarded to the result stream.
