Unify coroutine intrinsic docs

libraries/stdlib/coroutines/common/src/kotlin/CoroutinesIntrinsicsH.kt

@@ -6,12 +6,19 @@
 package kotlin.coroutines.intrinsics
 
 import kotlin.coroutines.Continuation
+import kotlin.coroutines.ContinuationInterceptor
+import kotlin.coroutines.CoroutineContext
 
 /**
  * Starts unintercepted coroutine without receiver and with result type [T] and executes it until its first suspension.
  * Returns the result of the coroutine or throws its exception if it does not suspend or [COROUTINE_SUSPENDED] if it suspends.
  * In the later case, the [completion] continuation is invoked when coroutine completes with result or exception.
- * This function is designed to be used from inside of [suspendCoroutineOrReturn] to resume the execution of suspended
+ *
+ * The coroutine is started directly in the invoker's thread without going through the [ContinuationInterceptor] that might
+ * be present in the completion's [CoroutineContext]. It is invoker's responsibility to ensure that the proper invocation
+ * context is established.
+ *
+ * This function is designed to be used from inside of [suspendCoroutineUninterceptedOrReturn] to resume the execution of suspended
  * coroutine using a reference to the suspending function.
  */
 @SinceKotlin("1.3")
@@ -23,7 +30,12 @@ public expect inline fun <T> (suspend () -> T).startCoroutineUninterceptedOrRetu
  * Starts unintercepted coroutine with receiver type [R] and result type [T] and executes it until its first suspension.
  * Returns the result of the coroutine or throws its exception if it does not suspend or [COROUTINE_SUSPENDED] if it suspends.
  * In the later case, the [completion] continuation is invoked when coroutine completes with result or exception.
- * This function is designed to be used from inside of [suspendCoroutineOrReturn] to resume the execution of suspended
+ *
+ * The coroutine is started directly in the invoker's thread without going through the [ContinuationInterceptor] that might
+ * be present in the completion's [CoroutineContext]. It is invoker's responsibility to ensure that the proper invocation
+ * context is established.
+ *
+ * This function is designed to be used from inside of [suspendCoroutineUninterceptedOrReturn] to resume the execution of suspended
  * coroutine using a reference to the suspending function.
  */
 @SinceKotlin("1.3")
@@ -43,5 +55,14 @@ public expect fun <R, T> (suspend R.() -> T).createCoroutineUnintercepted(
     completion: Continuation<T>
 ): Continuation<Unit>
 
+/**
+ * Intercepts this continuation with [ContinuationInterceptor].
+ *
+ * This function shall be used on the immediate result of [createCoroutineUnintercepted] or [suspendCoroutineUninterceptedOrReturn],
+ * in which case it checks for [ContinuationInterceptor] in the continuation's [context][Continuation.context],
+ * invokes [ContinuationInterceptor.interceptContinuation], caches and returns result.
+ *
+ * If this function is invoked on other [Continuation] instances it returns `this` continuation unchanged.
+ */
 @SinceKotlin("1.3")
 public expect fun <T> Continuation<T>.intercepted(): Continuation<T>

libraries/stdlib/coroutines/js/src/kotlin/coroutines/intrinsics/IntrinsicsJs.kt

@@ -54,10 +54,15 @@ public actual inline fun <R, T> (suspend R.() -> T).startCoroutineUninterceptedO
  * The [completion] continuation is invoked when coroutine completes with result or exception.
  *
  * This function returns unintercepted continuation.
- * Invocation of `resume(Unit)` starts coroutine directly in the invoker's thread without going through the
+ * Invocation of `resume(Unit)` starts coroutine immediately in the invoker's call stack without going through the
  * [ContinuationInterceptor] that might be present in the completion's [CoroutineContext].
  * It is invoker's responsibility to ensure that the proper invocation context is established.
+ * Note that [completion] of this function may get invoked in an arbitrary context.
+ *
  * [Continuation.intercepted] can be used to acquire the intercepted continuation.
+ * Invocation of `resume(Unit)` on intercepted continuation guarantees that execution of
+ * both the coroutine and [completion] happens in the invocation context established by
+ * [ContinuationInterceptor].
  *
  * Repeated invocation of any resume function on the resulting continuation corrupts the
  * state machine of the coroutine and may result in arbitrary behaviour or exception.
@@ -84,10 +89,15 @@ public actual fun <T> (suspend () -> T).createCoroutineUnintercepted(
  * The [completion] continuation is invoked when coroutine completes with result or exception.
  *
  * This function returns unintercepted continuation.
- * Invocation of `resume(Unit)` starts coroutine directly in the invoker's thread without going through the
+ * Invocation of `resume(Unit)` starts coroutine immediately in the invoker's call stack without going through the
  * [ContinuationInterceptor] that might be present in the completion's [CoroutineContext].
  * It is invoker's responsibility to ensure that the proper invocation context is established.
+ * Note that [completion] of this function may get invoked in an arbitrary context.
+ *
  * [Continuation.intercepted] can be used to acquire the intercepted continuation.
+ * Invocation of `resume(Unit)` on intercepted continuation guarantees that execution of
+ * both the coroutine and [completion] happens in the invocation context established by
+ * [ContinuationInterceptor].
  *
  * Repeated invocation of any resume function on the resulting continuation corrupts the
  * state machine of the coroutine and may result in arbitrary behaviour or exception.
@@ -109,6 +119,12 @@ public actual fun <R, T> (suspend R.() -> T).createCoroutineUnintercepted(
 
 /**
  * Intercepts this continuation with [ContinuationInterceptor].
+ *
+ * This function shall be used on the immediate result of [createCoroutineUnintercepted] or [suspendCoroutineUninterceptedOrReturn],
+ * in which case it checks for [ContinuationInterceptor] in the continuation's [context][Continuation.context],
+ * invokes [ContinuationInterceptor.interceptContinuation], caches and returns result.
+ *
+ * If this function is invoked on other [Continuation] instances it returns `this` continuation unchanged.
  */
 @SinceKotlin("1.3")
 public actual fun <T> Continuation<T>.intercepted(): Continuation<T> =