Update the documentation of time-based operators

Author: dkhalanskyjb

Diff for: kotlinx-coroutines-core/common/src/Delay.kt

@@ -117,7 +117,14 @@ public suspend fun awaitCancellation(): Nothing = suspendCancellableCoroutine {}
  *
  * Note that delay can be used in [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
  *
- * Implementation note: how exactly time is tracked is an implementation detail of [CoroutineDispatcher] in the context.
+ * By default, on the JVM and Native, a `Dispatchers.IO` thread is used to calculate when the delay has passed,
+ * whereas on JS, the `Window.setTimeout` function is used, and on Wasm/WASI, `poll_oneoff` with the monotonic clock
+ * event type is used.
+ * It is possible for a [CoroutineDispatcher] to override this behavior and provide its own implementation
+ * of time tracking.
+ * For example, [Dispatchers.Main] typically uses the main thread's event loop to track time.
+ * However, the functionality of defining custom time tracking is not exposed to the public API.
+ *
  * @param timeMillis time in milliseconds.
  */
 public suspend fun delay(timeMillis: Long) {
@@ -143,7 +150,13 @@ public suspend fun delay(timeMillis: Long) {
  *
  * Note that delay can be used in [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
  *
- * Implementation note: how exactly time is tracked is an implementation detail of [CoroutineDispatcher] in the context.
+ * By default, on the JVM and Native, a `Dispatchers.IO` thread is used to calculate when the delay has passed,
+ * whereas on JS, the `Window.setTimeout` function is used, and on Wasm/WASI, `poll_oneoff` with the monotonic clock
+ * event type is used.
+ * It is possible for a [CoroutineDispatcher] to override this behavior and provide its own implementation
+ * of time tracking.
+ * For example, [Dispatchers.Main] typically uses the main thread's event loop to track time.
+ * However, the functionality of defining custom time tracking is not exposed to the public API.
  */
 public suspend fun delay(duration: Duration): Unit = delay(duration.toDelayMillis())
 

Diff for: kotlinx-coroutines-core/common/src/Timeout.kt

@@ -31,7 +31,7 @@ import kotlin.time.Duration.Companion.milliseconds
  * [Asynchronous timeout and resources](https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html#asynchronous-timeout-and-resources)
  * section of the coroutines guide for details.
  *
- * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
+ * For a description of how waiting for a specific duration is implemented, see [delay].
  *
  * @param timeMillis timeout time in milliseconds.
  */
@@ -63,7 +63,7 @@ public suspend fun <T> withTimeout(timeMillis: Long, block: suspend CoroutineSco
  * [Asynchronous timeout and resources](https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html#asynchronous-timeout-and-resources)
  * section of the coroutines guide for details.
  *
- * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
+ * For a description of how waiting for a specific duration is implemented, see [delay].
  */
 public suspend fun <T> withTimeout(timeout: Duration, block: suspend CoroutineScope.() -> T): T {
     contract {

Diff for: kotlinx-coroutines-core/common/src/flow/SharingStarted.kt

@@ -96,6 +96,8 @@ public fun interface SharingStarted {
          *
          * This function throws [IllegalArgumentException] when either [stopTimeoutMillis] or [replayExpirationMillis]
          * are negative.
+         *
+         * For a description of how waiting for a specific duration is implemented, see [delay].
          */
         @Suppress("FunctionName")
         public fun WhileSubscribed(
@@ -129,6 +131,8 @@ public fun interface SharingStarted {
  *
  * This function throws [IllegalArgumentException] when either [stopTimeout] or [replayExpiration]
  * are negative.
+ *
+ * For a description of how waiting for a specific duration is implemented, see [delay].
  */
 @Suppress("FunctionName")
 public fun SharingStarted.Companion.WhileSubscribed(

Diff for: kotlinx-coroutines-core/common/src/flow/operators/Delay.kt

@@ -56,6 +56,8 @@ fun main() = runBlocking {
  *
  * Note that the resulting flow does not emit anything as long as the original flow emits
  * items faster than every [timeoutMillis] milliseconds.
+ *
+ * For a description of how waiting for a specific duration is implemented, see [delay].
  */
 @FlowPreview
 public fun <T> Flow<T>.debounce(timeoutMillis: Long): Flow<T> {
@@ -104,6 +106,8 @@ public fun <T> Flow<T>.debounce(timeoutMillis: Long): Flow<T> {
  * Note that the resulting flow does not emit anything as long as the original flow emits
  * items faster than every [timeoutMillis] milliseconds.
  *
+ * For a description of how waiting for a specific duration is implemented, see [delay].
+ *
  * @param timeoutMillis [T] is the emitted value and the return value is timeout in milliseconds.
  */
 @FlowPreview
@@ -142,6 +146,8 @@ public fun <T> Flow<T>.debounce(timeoutMillis: (T) -> Long): Flow<T> =
  *
  * Note that the resulting flow does not emit anything as long as the original flow emits
  * items faster than every [timeout] milliseconds.
+ *
+ * For a description of how waiting for a specific duration is implemented, see [delay].
  */
 @FlowPreview
 public fun <T> Flow<T>.debounce(timeout: Duration): Flow<T> =
@@ -187,6 +193,8 @@ public fun <T> Flow<T>.debounce(timeout: Duration): Flow<T> =
  * Note that the resulting flow does not emit anything as long as the original flow emits
  * items faster than every [timeout] unit.
  *
+ * For a description of how waiting for a specific duration is implemented, see [delay].
+ *
  * @param timeout [T] is the emitted value and the return value is timeout in [Duration].
  */
 @FlowPreview
@@ -264,6 +272,8 @@ private fun <T> Flow<T>.debounceInternal(timeoutMillisSelector: (T) -> Long): Fl
  * <!--- TEST -->
  *
  * Note that the latest element is not emitted if it does not fit into the sampling window.
+ *
+ * For a description of how waiting for a specific duration is implemented, see [delay].
  */
 @FlowPreview
 public fun <T> Flow<T>.sample(periodMillis: Long): Flow<T> {
@@ -335,6 +345,8 @@ internal fun CoroutineScope.fixedPeriodTicker(
  * <!--- TEST -->
  *
  * Note that the latest element is not emitted if it does not fit into the sampling window.
+ *
+ * For a description of how waiting for a specific duration is implemented, see [delay].
  */
 @FlowPreview
 public fun <T> Flow<T>.sample(period: Duration): Flow<T> = sample(period.toDelayMillis())
@@ -377,6 +389,8 @@ public fun <T> Flow<T>.sample(period: Duration): Flow<T> = sample(period.toDelay
  *
  * Note that delaying on the downstream doesn't trigger the timeout.
  *
+ * For a description of how waiting for a specific duration is implemented, see [delay].
+ *
  * @param timeout Timeout duration. If non-positive, the flow is timed out immediately
  */
 @FlowPreview

Diff for: kotlinx-coroutines-core/common/src/selects/OnTimeout.kt

@@ -7,6 +7,8 @@ import kotlin.time.*
  * Clause that selects the given [block] after a specified timeout passes.
  * If timeout is negative or zero, [block] is selected immediately.
  *
+ * For a description of how waiting for a specific duration is implemented, see [delay].
+ *
  * **Note: This is an experimental api.** It may be replaced with light-weight timer/timeout channels in the future.
  *
  * @param timeMillis timeout time in milliseconds.
@@ -20,6 +22,8 @@ public fun <R> SelectBuilder<R>.onTimeout(timeMillis: Long, block: suspend () ->
  * Clause that selects the given [block] after the specified [timeout] passes.
  * If timeout is negative or zero, [block] is selected immediately.
  *
+ * For a description of how waiting for a specific duration is implemented, see [delay].
+ *
  * **Note: This is an experimental api.** It may be replaced with light-weight timer/timeout channels in the future.
  */
 @ExperimentalCoroutinesApi