Update various documentations.

Documents Stream.timeout better.
Documents that collection.cast doesn't affect
methods accepting `Object?`.

Fixes #30163
Documents issue of #46336

Bug: http://dartbug.com/30163
Change-Id: Ie228a81d838a14c383da2f75af8b5dbb31e8ea3d
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/208651
Commit-Queue: Lasse R.H. Nielsen <[email protected]>
Commit-Queue: Erik Ernst <[email protected]>
Auto-Submit: Lasse R.H. Nielsen <[email protected]>
Reviewed-by: Erik Ernst <[email protected]>

Author: lrhn

sdk/lib/async/stream.dart

@@ -1479,24 +1479,31 @@ abstract class Stream<T> {
 
   /// 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, which can emit further events on
+  /// When someone is listening on the returned stream and more than
+  /// [timeLimit] passes without any event being emitted by this stream,
+  /// the [onTimeout] function is called, which can then 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 this stream is paused and resumed.
+  /// The countdown starts when the returned stream is listened to,
+  /// and is restarted when an event from the this stream is emitted,
+  /// or when listening on the returned stream is paused and resumed.
+  /// 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.
+  /// If the delay between events of this stream is multiple times
+  /// [timeLimit], at most one timeout will happen between events.
   ///
   /// 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].
   /// Calling [EventSink.close] on the sink passed to [onTimeout] closes the
   /// returned stream, and no further events are processed.
   ///
-  /// If [onTimeout] is omitted, a timeout will just put a [TimeoutException]
+  /// If [onTimeout] is omitted, a timeout will emit a [TimeoutException]
   /// into the error channel of the returned stream.
-  /// If the call to [onTimeout] throws, the error is emitted on the returned
-  /// stream.
+  /// If the call to [onTimeout] throws, the error is emitted as an error
+  /// 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
@@ -1519,8 +1526,6 @@ abstract class Stream<T> {
             new TimeoutException("No stream event", timeLimit), null);
       };
     } else {
-      // TODO(floitsch): the return type should be 'void', and the type
-      // should be inferred.
       var registeredOnTimeout =
           zone.registerUnaryCallback<void, EventSink<T>>(onTimeout);
       var wrapper = new _ControllerEventSinkWrapper<T>(null);

sdk/lib/collection/queue.dart

@@ -52,6 +52,11 @@ abstract class Queue<E> implements EfficientLengthIterable<E> {
   /// and if all elements stored into the returned queue are actually instance
   /// of [S],
   /// then the returned queue can be used as a `Queue<T>`.
+  ///
+  /// Methods like [contains] and [remove]
+  /// which accept one `Object?` as argument,
+  /// will pass the argument directly to the this queue's method
+  /// without any checks.
   static Queue<T> castFrom<S, T>(Queue<S> source) => CastQueue<S, T>(source);
 
   /// Provides a view of this queue as a queue of [R] instances, if necessary.
@@ -64,6 +69,13 @@ abstract class Queue<E> implements EfficientLengthIterable<E> {
   /// must be instance of [R] to be valid arguments to the adding function,
   /// and they must be instances of [E] as well to be accepted by
   /// this queue as well.
+  ///
+  /// Methods like [contains] and [remove]
+  /// which accept one `Object?` as argument,
+  /// will pass the argument directly to the this queue's method
+  /// without any checks.
+  /// That means that you can do `queueOfStrings.cast<int>().remove("a")`
+  /// successfully, even if it looks like it shouldn't have any effect.
   Queue<R> cast<R>();
 
   /// Removes and returns the first element of this queue.
@@ -304,6 +316,7 @@ class DoubleLinkedQueue<E> extends Iterable<E> implements Queue<E> {
       DoubleLinkedQueue<E>()..addAll(elements);
 
   Queue<R> cast<R>() => Queue.castFrom<E, R>(this);
+
   int get length => _elementCount;
 
   void addLast(E value) {

sdk/lib/core/list.dart

@@ -187,6 +187,11 @@ abstract class List<E> implements EfficientLengthIterable<E> {
   /// and if all elements stored into the returned list are actually instance
   /// of [S],
   /// then the returned list can be used as a `List<T>`.
+  ///
+  /// Methods like [contains] and [remove]
+  /// which accept `Object?` as argument
+  /// will pass the argument directly to the this list's method
+  /// without any checks.
   static List<T> castFrom<S, T>(List<S> source) => CastList<S, T>(source);
 
   /// Copy a range of one list into another list.
@@ -254,14 +259,21 @@ abstract class List<E> implements EfficientLengthIterable<E> {
   /// Returns a view of this list as a list of [R] instances.
   ///
   /// If this list contains only instances of [R], all read operations
-  /// will work correctly. If any operation tries to access an element
+  /// will work correctly. If any operation tries to read an element
   /// that is not an instance of [R], the access will throw instead.
   ///
   /// Elements added to the list (e.g., by using [add] or [addAll])
   /// must be instance of [R] to be valid arguments to the adding function,
   /// and they must be instances of [E] as well to be accepted by
   /// this list as well.
   ///
+  /// Methods like [contains] and [remove]
+  /// which accept `Object?` as argument
+  /// will pass the argument directly to the this list's method
+  /// without any checks.
+  /// That means that you can do `listOfStrings.cast<int>().remove("a")`
+  /// successfully, even if it looks like it shouldn't have any effect.
+  ///
   /// Typically implemented as `List.castFrom<E, R>(this)`.
   List<R> cast<R>();
 

sdk/lib/core/map.dart

@@ -163,6 +163,11 @@ abstract class Map<K, V> {
   /// If all accessed entries of [source] are have [K2] keys and [V2] values
   /// and if all entries added to the returned map have [K] keys and [V]] values,
   /// then the returned map can be used as a `Map<K2, V2>`.
+  ///
+  /// Methods like [containsKey], [remove] and [operator[]]
+  /// which accept `Object?` as argument
+  /// will pass the argument directly to the this map's method
+  /// without any checks.
   static Map<K2, V2> castFrom<K, V, K2, V2>(Map<K, V> source) =>
       CastMap<K, V, K2, V2>(source);
 
@@ -193,6 +198,13 @@ abstract class Map<K, V> {
   ///
   /// Entries added to the map must be valid for both a `Map<K, V>` and a
   /// `Map<RK, RV>`.
+  ///
+  /// Methods like [containsKey], [remove] and [operator[]]
+  /// which accept `Object?` as argument
+  /// will pass the argument directly to the this map's method
+  /// without any checks.
+  /// That means that you can do `mapWithStringKeys.cast<int,int>().remove("a")`
+  /// successfully, even if it looks like it shouldn't have any effect.
   Map<RK, RV> cast<RK, RV>();
 
   /// Whether this map contains the given [value].

sdk/lib/core/set.dart

@@ -106,6 +106,11 @@ abstract class Set<E> extends EfficientLengthIterable<E> {
   /// and if all elements added to the returned set are actually instance
   /// of [S],
   /// then the returned set can be used as a `Set<T>`.
+  ///
+  /// Methods like [contains], [remove] and [removeAll]
+  /// which accept one or more `Object?` as argument,
+  /// will pass the argument directly to the this set's method
+  /// without any checks.
   static Set<T> castFrom<S, T>(Set<S> source, {Set<R> Function<R>()? newSet}) =>
       CastSet<S, T>(source, newSet);
 
@@ -119,6 +124,13 @@ abstract class Set<E> extends EfficientLengthIterable<E> {
   /// must be instance of [R] to be valid arguments to the adding function,
   /// and they must be instances of [E] as well to be accepted by
   /// this set as well.
+  ///
+  /// Methods like [contains], [remove] and [removeAll]
+  /// which accept one or more `Object?` as argument,
+  /// will pass the argument directly to the this set's method
+  /// without any checks.
+  /// That means that you can do `setOfStrings.cast<int>().remove("a")`
+  /// successfully, even if it looks like it shouldn't have any effect.
   Set<R> cast<R>();
 
   /// An iterator that iterates over the elements of this set.