Clarify withContext(NonCancellable) behavior (#2400)

Fixes #2383
Kotlin · Nov 18, 2020 · 81577b2 · 81577b2
1 parent 31a8df0
commit 81577b2
Showing 1 changed file with 4 additions and 0 deletions.
diff --git a/kotlinx-coroutines-core/common/src/Builders.common.kt b/kotlinx-coroutines-core/common/src/Builders.common.kt
@@ -133,6 +133,10 @@ private class LazyDeferredCoroutine<T>(
  * which means that if the original [coroutineContext], in which `withContext` was invoked,
  * is cancelled by the time its dispatcher starts to execute the code,
  * it discards the result of `withContext` and throws [CancellationException].
+ *
+ * The cancellation behaviour described above is enabled if and only if the dispatcher is being changed.
+ * For example, when using `withContext(NonCancellable) { ... }` there is no change in dispatcher and
+ * this call will not be cancelled neither on entry to the block inside `withContext` nor on exit from it.
  */
 public suspend fun <T> withContext(
     context: CoroutineContext,