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.