Better NonCancellable docs (Kotlin#2633)

pablobaxter · Sep 14, 2022 · 954503e · 954503e
1 parent bbb5415
commit 954503e
Showing 1 changed file with 5 additions and 0 deletions.
diff --git a/kotlinx-coroutines-core/common/src/NonCancellable.kt b/kotlinx-coroutines-core/common/src/NonCancellable.kt
@@ -18,6 +18,11 @@ import kotlin.coroutines.*
  *     // this code will not be cancelled
  * }
  * ```
+ *
+ * **WARNING**: This object is not designed to be used with [launch], [async], and other coroutine builders.
+ * if you write `launch(NonCancellable) { ... }` then not only the newly launched job will not be cancelled
+ * when the parent is cancelled, the whole parent-child relation between parent and child is severed.
+ * The parent will not wait for the child's completion, nor will be cancelled when the child crashed.
  */
 public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
     /**