Repository: kotlin/kotlinx.coroutines
Issue: Flow.timeout documentation suggests generic `catch {}` operator.

The API documentation for `Flow<T>.timeout` suggests using a `catch{}` without rethrowing:

```
flow {
    emit(1)
    delay(100)
    emit(2)
    delay(100)
    emit(3)
    delay(1000)
    emit(4)
}.timeout(100.milliseconds).catch {
    emit(-1) // Item to emit on timeout
}.onEach {
    delay(300) // This will not cause a timeout
}
```

This will emit -1 for any and all upstream exceptions (admittedly none other possible in this fizz buzz example). Can we update the documentation to be more targeted?

Such as this.

```
flow {
    emit(1)
    delay(100)
    emit(2)
    delay(100)
    emit(3)
    delay(1000)
    emit(4)
}.timeout(100.milliseconds).catch { exception ->
    if (exception is TimeoutCancellationException) {
      // Catch the TimeoutCancellationException emitted above.
      emit(-1) // Item to emit on timeout
    } else {
      throw exception
    }
}.onEach {
    delay(300) // This will not cause a timeout
}
```

Changed files:
kotlinx-coroutines-core/common/src/flow/operators/Delay.kt
kotlinx-coroutines-core/jvm/test/examples/example-timeout-duration-01.kt

diff --git a/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt b/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt
index 37505dc16..e498e5296 100644
--- a/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt
+++ b/kotlinx-coroutines-core/common/src/flow/operators/Delay.kt
@@ -203,7 +203,7 @@ public fun <T> Flow<T>.debounce(timeout: (T) -> Duration): Flow<T> =
         timeout(emittedItem).toDelayMillis()
     }
 
-private fun <T> Flow<T>.debounceInternal(timeoutMillisSelector: (T) -> Long) : Flow<T> =
+private fun <T> Flow<T>.debounceInternal(timeoutMillisSelector: (T) -> Long): Flow<T> =
     scopedFlow { downstream ->
         // Produce the values using the default (rendezvous) channel
         val values = produce {
@@ -306,7 +306,10 @@ public fun <T> Flow<T>.sample(periodMillis: Long): Flow<T> {
 /*
  * TODO this design (and design of the corresponding operator) depends on #540
  */
-internal fun CoroutineScope.fixedPeriodTicker(delayMillis: Long, initialDelayMillis: Long = delayMillis): ReceiveChannel<Unit> {
+internal fun CoroutineScope.fixedPeriodTicker(
+    delayMillis: Long,
+    initialDelayMillis: Long = delayMillis
+): ReceiveChannel<Unit> {
     require(delayMillis >= 0) { "Expected non-negative delay, but has $delayMillis ms" }
     require(initialDelayMillis >= 0) { "Expected non-negative initial delay, but has $initialDelayMillis ms" }
     return produce(capacity = 0) {
@@ -359,8 +362,15 @@ public fun <T> Flow<T>.sample(period: Duration): Flow<T> = sample(period.toDelay
  *     emit(3)
  *     delay(1000)
  *     emit(4)
- * }.timeout(100.milliseconds).catch {
- *     emit(-1) // Item to emit on timeout
+ * }.timeout(100.milliseconds).catch { exception ->
+ *     if (exception is TimeoutCancellationException) {
+ *         // Catch the TimeoutCancellationException emitted above.
+ *         // Emit desired item on timeout.
+ *         emit(-1)
+ *     } else {
+ *         // Throw other exceptions.
+ *         throw exception
+ *     }
  * }.onEach {
  *     delay(300) // This will not cause a timeout
  * }
diff --git a/kotlinx-coroutines-core/jvm/test/examples/example-timeout-duration-01.kt b/kotlinx-coroutines-core/jvm/test/examples/example-timeout-duration-01.kt
index 5db6e6a52..5adda863c 100644
--- a/kotlinx-coroutines-core/jvm/test/examples/example-timeout-duration-01.kt
+++ b/kotlinx-coroutines-core/jvm/test/examples/example-timeout-duration-01.kt
@@ -19,8 +19,15 @@ flow {
     emit(3)
     delay(1000)
     emit(4)
-}.timeout(100.milliseconds).catch {
-    emit(-1) // Item to emit on timeout
+}.timeout(100.milliseconds).catch { exception ->
+    if (exception is TimeoutCancellationException) {
+        // Catch the TimeoutCancellationException emitted above.
+        // Emit desired item on timeout.
+        emit(-1)
+    } else {
+        // Throw other exceptions.
+        throw exception
+    }
 }.onEach {
     delay(300) // This will not cause a timeout
 }