Update delay and withTimeout* documentation

Fixes #3373

Author: qwwdfsad

kotlinx-coroutines-core/common/src/Delay.kt

@@ -94,6 +94,7 @@ public suspend fun awaitCancellation(): Nothing = suspendCancellableCoroutine {}
 
 /**
  * Delays coroutine for a given time without blocking a thread and resumes it after a specified time.
+ * If the given [timeMillis] is non-positive, this function returns immediately.
  *
  * This suspending function is cancellable.
  * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
@@ -120,6 +121,7 @@ public suspend fun delay(timeMillis: Long) {
 
 /**
  * Delays coroutine for a given [duration] without blocking a thread and resumes it after the specified time.
+ * If the given [duration] is non-positive, this function returns immediately.
  *
  * This suspending function is cancellable.
  * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function

kotlinx-coroutines-core/common/src/Timeout.kt

@@ -17,6 +17,7 @@ import kotlin.time.*
 /**
  * Runs a given suspending [block] of code inside a coroutine with a specified [timeout][timeMillis] and throws
  * a [TimeoutCancellationException] if the timeout was exceeded.
+ * If the given [timeMillis] is non-positive, [TimeoutCancellationException] is thrown immediately.
  *
  * The code that is executing inside the [block] is cancelled on timeout and the active or next invocation of
  * the cancellable suspending function inside the block throws a [TimeoutCancellationException].
@@ -25,8 +26,8 @@ import kotlin.time.*
  * Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
  *
  * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
- * even right before the return from inside of the timeout [block]. Keep this in mind if you open or acquire some
- * resource inside the [block] that needs closing or release outside of the block.
+ * even right before the return from inside the timeout [block]. Keep this in mind if you open or acquire some
+ * resource inside the [block] that needs closing or release outside the block.
  * See the
  * [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.
@@ -48,6 +49,7 @@ public suspend fun <T> withTimeout(timeMillis: Long, block: suspend CoroutineSco
 /**
  * Runs a given suspending [block] of code inside a coroutine with the specified [timeout] and throws
  * a [TimeoutCancellationException] if the timeout was exceeded.
+ * If the given [timeout] is non-positive, [TimeoutCancellationException] is thrown immediately.
  *
  * The code that is executing inside the [block] is cancelled on timeout and the active or next invocation of
  * the cancellable suspending function inside the block throws a [TimeoutCancellationException].
@@ -56,8 +58,8 @@ public suspend fun <T> withTimeout(timeMillis: Long, block: suspend CoroutineSco
  * Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
  *
  * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
- * even right before the return from inside of the timeout [block]. Keep this in mind if you open or acquire some
- * resource inside the [block] that needs closing or release outside of the block.
+ * even right before the return from inside the timeout [block]. Keep this in mind if you open or acquire some
+ * resource inside the [block] that needs closing or release outside the block.
  * See the
  * [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.
@@ -74,6 +76,7 @@ public suspend fun <T> withTimeout(timeout: Duration, block: suspend CoroutineSc
 /**
  * Runs a given suspending block of code inside a coroutine with a specified [timeout][timeMillis] and returns
  * `null` if this timeout was exceeded.
+ * If the given [timeMillis] is non-positive, `null` is returned immediately.
  *
  * The code that is executing inside the [block] is cancelled on timeout and the active or next invocation of
  * cancellable suspending function inside the block throws a [TimeoutCancellationException].
@@ -82,8 +85,8 @@ public suspend fun <T> withTimeout(timeout: Duration, block: suspend CoroutineSc
  * Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
  *
  * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
- * even right before the return from inside of the timeout [block]. Keep this in mind if you open or acquire some
- * resource inside the [block] that needs closing or release outside of the block.
+ * even right before the return from inside the timeout [block]. Keep this in mind if you open or acquire some
+ * resource inside the [block] that needs closing or release outside the block.
  * See the
  * [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.
@@ -114,6 +117,7 @@ public suspend fun <T> withTimeoutOrNull(timeMillis: Long, block: suspend Corout
 /**
  * Runs a given suspending block of code inside a coroutine with the specified [timeout] and returns
  * `null` if this timeout was exceeded.
+ * If the given [timeout] is non-positive, `null` is returned immediately.
  *
  * The code that is executing inside the [block] is cancelled on timeout and the active or next invocation of
  * cancellable suspending function inside the block throws a [TimeoutCancellationException].
@@ -122,8 +126,8 @@ public suspend fun <T> withTimeoutOrNull(timeMillis: Long, block: suspend Corout
  * Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
  *
  * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
- * even right before the return from inside of the timeout [block]. Keep this in mind if you open or acquire some
- * resource inside the [block] that needs closing or release outside of the block.
+ * even right before the return from inside the timeout [block]. Keep this in mind if you open or acquire some
+ * resource inside the [block] that needs closing or release outside the block.
  * See the
  * [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.
@@ -177,7 +181,6 @@ public class TimeoutCancellationException internal constructor(
         TimeoutCancellationException(message ?: "", coroutine).also { it.initCause(this) }
 }
 
-@Suppress("FunctionName")
 internal fun TimeoutCancellationException(
     time: Long,
     coroutine: Job