1 files changed, 23 insertions, 13 deletions

diff --git a/kotlinx-coroutines-core/common/src/NonCancellable.kt b/kotlinx-coroutines-core/common/src/NonCancellable.kt
index a9c68f09..c2781092 100644
--- a/kotlinx-coroutines-core/common/src/NonCancellable.kt
+++ b/kotlinx-coroutines-core/common/src/NonCancellable.kt
@@ -18,41 +18,51 @@ 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.
  */
+@Suppress("DeprecatedCallableAddReplaceWith")
 public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
+
+    private const val message = "NonCancellable can be used only as an argument for 'withContext', direct usages of its API are prohibited"
+
     /**
      * Always returns `true`.
      * @suppress **This an internal API and should not be used from general code.**
      */
-    @InternalCoroutinesApi
-    override val isActive: Boolean get() = true
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
+    override val isActive: Boolean
+        get() = true
 
     /**
      * Always returns `false`.
      * @suppress **This an internal API and should not be used from general code.**
      */
-    @InternalCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
     override val isCompleted: Boolean get() = false
 
     /**
      * Always returns `false`.
      * @suppress **This an internal API and should not be used from general code.**
      */
-    @InternalCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
     override val isCancelled: Boolean get() = false
 
     /**
      * Always returns `false`.
      * @suppress **This an internal API and should not be used from general code.**
      */
-    @InternalCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
     override fun start(): Boolean = false
 
     /**
      * Always throws [UnsupportedOperationException].
      * @suppress **This an internal API and should not be used from general code.**
      */
-    @InternalCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
     override suspend fun join() {
         throw UnsupportedOperationException("This job is always active")
     }
@@ -61,6 +71,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
      * Always throws [UnsupportedOperationException].
      * @suppress **This an internal API and should not be used from general code.**
      */
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
     override val onJoin: SelectClause0
         get() = throw UnsupportedOperationException("This job is always active")
 
@@ -68,14 +79,13 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
      * Always throws [IllegalStateException].
      * @suppress **This an internal API and should not be used from general code.**
      */
-    @InternalCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
     override fun getCancellationException(): CancellationException = throw IllegalStateException("This job is always active")
 
     /**
      * @suppress **This an internal API and should not be used from general code.**
      */
-    @Suppress("OverridingDeprecatedMember")
-    @InternalCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
     override fun invokeOnCompletion(handler: CompletionHandler): DisposableHandle =
         NonDisposableHandle
 
@@ -83,7 +93,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
      * Always returns no-op handle.
      * @suppress **This an internal API and should not be used from general code.**
      */
-    @InternalCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
     override fun invokeOnCompletion(onCancelling: Boolean, invokeImmediately: Boolean, handler: CompletionHandler): DisposableHandle =
         NonDisposableHandle
 
@@ -91,7 +101,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
      * Does nothing.
      * @suppress **This an internal API and should not be used from general code.**
      */
-    @InternalCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
     override fun cancel(cause: CancellationException?) {}
 
     /**
@@ -105,7 +115,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
      * Always returns [emptySequence].
      * @suppress **This an internal API and should not be used from general code.**
      */
-    @InternalCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
     override val children: Sequence<Job>
         get() = emptySequence()
 
@@ -113,7 +123,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
      * Always returns [NonDisposableHandle] and does not do anything.
      * @suppress **This an internal API and should not be used from general code.**
      */
-    @InternalCoroutinesApi
+    @Deprecated(level = DeprecationLevel.WARNING, message = message)
     override fun attachChild(child: ChildJob): ChildHandle = NonDisposableHandle
 
     /** @suppress */