diff --git a/sdk/lib/async/stream.dart b/sdk/lib/async/stream.dart
index f400c8415eda..7f49694f0fc9 100644
--- a/sdk/lib/async/stream.dart
+++ b/sdk/lib/async/stream.dart
@@ -2001,7 +2001,9 @@ abstract mixin class Stream<T> {
   /// The countdown is stopped when listening on the returned stream is
   /// paused or cancelled.
   /// No new countdown is started when a countdown completes
-  /// and the [onTimeout] function is called, even if events are emitted.
+  /// and the [onTimeout] function is called, even if events are emitted by the
+  /// [EventSink] provided by [onTimeout]. The countdown is only restarted when
+  /// a new event comes from this stream.
   /// If the delay between events of this stream is multiple times
   /// [timeLimit], at most one timeout will happen between events.
   ///