Don't say that job completion causes CancellationException

What does it even mean?

Author: dkhalanskyjb

integration/kotlinx-coroutines-guava/src/ListenableFuture.kt

@@ -216,7 +216,7 @@ public fun <T> Deferred<T>.asListenableFuture(): ListenableFuture<T> {
  *
  * This suspend function is cancellable.
  *
- * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
+ * If the [Job] of the current coroutine is cancelled while this suspending function is waiting, this function
  * stops waiting for the future and immediately resumes with [CancellationException][kotlinx.coroutines.CancellationException].
  *
  * This method is intended to be used with one-shot Futures, so on coroutine cancellation, the Future is cancelled as well.

integration/kotlinx-coroutines-play-services/src/Tasks.kt

@@ -94,7 +94,7 @@ private fun <T> Task<T>.asDeferredImpl(cancellationTokenSource: CancellationToke
  * Awaits the completion of the task without blocking a thread.
  *
  * This suspending function is cancellable.
- * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
+ * If the [Job] of the current coroutine is cancelled while this suspending function is waiting, this function
  * stops waiting for the completion stage and immediately resumes with [CancellationException].
  *
  * For bi-directional cancellation, an overload that accepts [CancellationTokenSource] can be used.
@@ -105,7 +105,7 @@ public suspend fun <T> Task<T>.await(): T = awaitImpl(null)
  * Awaits the completion of the task that is linked to the given [CancellationTokenSource] to control cancellation.
  *
  * This suspending function is cancellable and cancellation is bi-directional:
- * - If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
+ * - If the [Job] of the current coroutine is cancelled while this suspending function is waiting, this function
  * cancels the [cancellationTokenSource] and throws a [CancellationException].
  * - If the task is cancelled, then this function will throw a [CancellationException].
  *

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

@@ -11,7 +11,7 @@ import kotlin.coroutines.*
  * This function is **not** equivalent to `deferreds.map { it.await() }` which fails only when it sequentially
  * gets to wait for the failing deferred, while this `awaitAll` fails immediately as soon as any of the deferreds fail.
  *
- * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+ * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
  * suspending function is waiting, this function immediately resumes with [CancellationException].
  * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
  * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.
@@ -27,7 +27,7 @@ public suspend fun <T> awaitAll(vararg deferreds: Deferred<T>): List<T> =
  * This function is **not** equivalent to `this.map { it.await() }` which fails only when it sequentially
  * gets to wait for the failing deferred, while this `awaitAll` fails immediately as soon as any of the deferreds fail.
  *
- * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+ * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
  * suspending function is waiting, this function immediately resumes with [CancellationException].
  * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
  * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.
@@ -39,7 +39,7 @@ public suspend fun <T> Collection<Deferred<T>>.awaitAll(): List<T> =
  * Suspends current coroutine until all given jobs are complete.
  * This method is semantically equivalent to joining all given jobs one by one with `jobs.forEach { it.join() }`.
  *
- * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+ * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
  * suspending function is waiting, this function immediately resumes with [CancellationException].
  * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
  * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.
@@ -50,7 +50,7 @@ public suspend fun joinAll(vararg jobs: Job): Unit = jobs.forEach { it.join() }
  * Suspends current coroutine until all given jobs are complete.
  * This method is semantically equivalent to joining all given jobs one by one with `forEach { it.join() }`.
  *
- * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+ * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
  * suspending function is waiting, this function immediately resumes with [CancellationException].
  * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
  * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.

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

@@ -106,7 +106,7 @@ public suspend fun awaitCancellation(): Nothing = suspendCancellableCoroutine {}
  * Delays coroutine for at least the 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
+ * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
  * suspending function is waiting, this function immediately resumes with [CancellationException].
  * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
  * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.
@@ -132,7 +132,7 @@ public suspend fun delay(timeMillis: Long) {
  * Delays coroutine for at least the 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
+ * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
  * suspending function is waiting, this function immediately resumes with [CancellationException].
  * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
  * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.

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

@@ -7,7 +7,7 @@ import kotlin.coroutines.intrinsics.*
  * Yields the thread (or thread pool) of the current coroutine dispatcher
  * to other coroutines on the same dispatcher to run if possible.
  *
- * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while
+ * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while
  * [yield] is invoked or while waiting for dispatch, it immediately resumes with [CancellationException].
  * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
  * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.

kotlinx-coroutines-core/common/src/channels/Channel.kt

@@ -41,7 +41,7 @@ public interface SendChannel<in E> {
      * All elements sent over the channel are delivered in first-in first-out order. The sent element
      * will be delivered to receivers before the close token.
      *
-     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
      * suspending function is waiting, this function immediately resumes with [CancellationException].
      * There is a **prompt cancellation guarantee**: even if [send] managed to send the element, but was cancelled
      * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.
@@ -212,14 +212,14 @@ public interface ReceiveChannel<out E> {
      * If the channel was closed because of an exception, it is called a _failed_ channel and this function
      * will throw the original [close][SendChannel.close] cause exception.
      *
-     * This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this
+     * This suspending function is cancellable. If the [Job] of the current coroutine is cancelled while this
      * function is suspended, this function immediately resumes with a [CancellationException].
      * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was
      * suspended, it will not resume successfully. The `receive` call can retrieve the element from the channel,
      * but then throw [CancellationException], thus failing to deliver the element.
      * See "Undelivered elements" section in [Channel] documentation for details on handling undelivered elements.
      *
-     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
      * suspending function is waiting, this function immediately resumes with [CancellationException].
      * There is a **prompt cancellation guarantee**: even if [receive] managed to retrieve the element from the channel,
      * but was cancelled while suspended, [CancellationException] will be thrown.
@@ -250,7 +250,7 @@ public interface ReceiveChannel<out E> {
      * or the close cause if the channel was closed. Closed cause may be `null` if the channel was closed normally.
      * The result cannot be [failed][ChannelResult.isFailure] without being [closed][ChannelResult.isClosed].
      *
-     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
      * suspending function is waiting, this function immediately resumes with [CancellationException].
      * There is a **prompt cancellation guarantee**: even if [receiveCatching] managed to retrieve the element from the
      * channel, but was cancelled while suspended, [CancellationException] will be thrown.
@@ -573,7 +573,7 @@ public interface ChannelIterator<out E> {
      * This function retrieves and removes an element from this channel for the subsequent invocation
      * of [next].
      *
-     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
      * suspending function is waiting, this function immediately resumes with [CancellationException].
      * There is a **prompt cancellation guarantee**: even if [hasNext] retrieves the element from the channel during
      * its operation, but was cancelled while suspended, [CancellationException] will be thrown.

kotlinx-coroutines-core/common/src/channels/Produce.kt

@@ -22,7 +22,7 @@ public interface ProducerScope<in E> : CoroutineScope, SendChannel<E> {
  * Suspends the current coroutine until the channel is either [closed][SendChannel.close] or [cancelled][ReceiveChannel.cancel]
  * and invokes the given [block] before resuming the coroutine.
  *
- * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+ * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
  * suspending function is waiting, this function immediately resumes with [CancellationException].
  * There is a **prompt cancellation guarantee**: even if this function is ready to return, but was cancelled
  * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.

kotlinx-coroutines-core/common/src/selects/Select.kt

@@ -38,7 +38,7 @@ import kotlin.jvm.*
  * | [ReceiveChannel] | [receiveCatching][ReceiveChannel.receiveCatching] | [onReceiveCatching][ReceiveChannel.onReceiveCatching]
  * | none             | [delay]                                           | [onTimeout][SelectBuilder.onTimeout]
  *
- * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+ * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
  * suspending function is waiting, this function immediately resumes with [CancellationException].
  * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
  * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.

kotlinx-coroutines-core/common/src/sync/Mutex.kt

@@ -40,7 +40,7 @@ public interface Mutex {
     /**
      * Locks this mutex, suspending caller until the lock is acquired (in other words, while the lock is held elsewhere).
      *
-     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
      * suspending function is waiting, this function immediately resumes with [CancellationException].
      * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
      * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.

kotlinx-coroutines-core/common/src/sync/Semaphore.kt

@@ -28,7 +28,7 @@ public interface Semaphore {
      * Acquires a permit from this semaphore, suspending until one is available.
      * All suspending acquirers are processed in first-in-first-out (FIFO) order.
      *
-     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+     * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
      * suspending function is waiting, this function immediately resumes with [CancellationException].
      * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
      * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.

kotlinx-coroutines-core/jdk8/src/future/Future.kt

@@ -146,7 +146,7 @@ public fun <T> CompletionStage<T>.asDeferred(): Deferred<T> {
  * Awaits for completion of [CompletionStage] without blocking a thread.
  *
  * This suspending function is cancellable.
- * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
+ * If the [Job] of the current coroutine is cancelled while this suspending function is waiting, this function
  * stops waiting for the completion stage and immediately resumes with [CancellationException][kotlinx.coroutines.CancellationException].
  *
  * This method is intended to be used with one-shot futures, so on coroutine cancellation the [CompletableFuture] that

kotlinx-coroutines-core/js/src/Promise.kt

@@ -55,7 +55,7 @@ public fun <T> Promise<T>.asDeferred(): Deferred<T> {
 /**
  * Awaits for completion of the promise without blocking.
  *
- * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+ * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
  * suspending function is waiting on the promise, this function immediately resumes with [CancellationException].
  * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
  * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.

kotlinx-coroutines-core/wasmJs/src/Promise.kt

@@ -66,7 +66,7 @@ public fun <T> Promise<JsAny?>.asDeferred(): Deferred<T> {
 /**
  * Awaits for completion of the promise without blocking.
  *
- * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled or completed while this
+ * This suspending function is cancellable: if the [Job] of the current coroutine is cancelled while this
  * suspending function is waiting on the promise, this function immediately resumes with [CancellationException].
  * There is a **prompt cancellation guarantee**: even if this function is ready to return the result, but was cancelled
  * while suspended, [CancellationException] will be thrown. See [suspendCancellableCoroutine] for low-level details.