Explain the typical dispatch procedure in CoroutineDispatcher docs

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

@@ -6,23 +6,55 @@ import kotlin.coroutines.*
 /**
  * Base class to be extended by all coroutine dispatcher implementations.
  *
+ * If `kotlinx-coroutines` is used, it is recommended to avoid [ContinuationInterceptor] instances that are not
+ * [CoroutineDispatcher] implementations, as [CoroutineDispatcher] ensures that the
+ * debugging facilities in the [newCoroutineContext] function work properly.
+ *
+ * ## Predefined dispatchers
+ *
  * The following standard implementations are provided by `kotlinx.coroutines` as properties on
  * the [Dispatchers] object:
  *
- * - [Dispatchers.Default] — is used by all standard builders if no dispatcher or any other [ContinuationInterceptor]
- *   is specified in their context. It uses a common pool of shared background threads.
+ * - [Dispatchers.Default] is used by all standard builders if no dispatcher or any other [ContinuationInterceptor]
+ *   is specified in their context.
+ *   It uses a common pool of shared background threads.
  *   This is an appropriate choice for compute-intensive coroutines that consume CPU resources.
- * - [Dispatchers.IO] — uses a shared pool of on-demand created threads and is designed for offloading of IO-intensive _blocking_
+ * - `Dispatchers.IO` (available on the JVM and Native targets)
+ *   uses a shared pool of on-demand created threads and is designed for offloading of IO-intensive _blocking_
  *   operations (like file I/O and blocking socket I/O).
- * - [Dispatchers.Unconfined] — starts coroutine execution in the current call-frame until the first suspension,
- *   whereupon the coroutine builder function returns.
- *   The coroutine will later resume in whatever thread used by the
- *   corresponding suspending function, without confining it to any specific thread or pool.
+ * - [Dispatchers.Main] represents the UI thread if one is available.
+ * - [Dispatchers.Unconfined] starts coroutine execution in the current call-frame until the first suspension,
+ *   at which point the coroutine builder function returns.
+ *   When the coroutine is resumed, the thread from which it is resumed will run the coroutine code until the next
+ *   suspension, and so on.
  *   **The `Unconfined` dispatcher should not normally be used in code**.
- * - Private thread pools can be created with [newSingleThreadContext] and [newFixedThreadPoolContext].
- * - An arbitrary [Executor][java.util.concurrent.Executor] can be converted to a dispatcher with the [asCoroutineDispatcher] extension function.
+ * - Calling [limitedParallelism] on any dispatcher creates a view of the dispatcher that limits the parallelism
+ *   to the given value.
+ *   This allows creating private thread pools without spawning new threads.
+ *   For example, `Dispatchers.IO.limitedParallelism(4)` creates a dispatcher that allows running at most
+ *   4 tasks in parallel, reusing the existing IO dispatcher threads.
+ * - When thread pools completely separate from [Dispatchers.Default] and [Dispatchers.IO] are required,
+ *   they can be created with `newSingleThreadContext` and `newFixedThreadPoolContext` on the JVM and Native targets.
+ * - An arbitrary `java.util.concurrent.Executor` can be converted to a dispatcher with the
+ *   `asCoroutineDispatcher` extension function.
+ *
+ * ## Dispatch procedure
  *
- * This class ensures that debugging facilities in [newCoroutineContext] function work properly.
+ * Typically, a dispatch procedure is performed as follows:
+ *
+ * - First, [isDispatchNeeded] is invoked to determine whether the coroutine should be dispatched
+ *   or is already in the right context.
+ * - If [isDispatchNeeded] returns `true`, the coroutine is dispatched using the [dispatch] method.
+ *   It may take a while for the dispatcher to start the task,
+ *   but the [dispatch] method itself may return immediately, before the task has even began to execute.
+ * - If no dispatch is needed (which is the case for [Dispatchers.Main.immediate][MainCoroutineDispatcher.immediate]
+ *   when already on the main thread and for [Dispatchers.Unconfined]),
+ *   the coroutine is resumed in the thread performing the dispatch procedure,
+ *   forming an event loop to prevent stack overflows.
+ *   See [Dispatchers.Unconfined] for a description of event loops.
+ *
+ * This behavior may be different on the very first dispatch procedure for a given coroutine, depending on the
+ * [CoroutineStart] parameter of the coroutine builder.
  */
 public abstract class CoroutineDispatcher :
     AbstractCoroutineContextElement(ContinuationInterceptor), ContinuationInterceptor {
@@ -205,7 +237,7 @@ public abstract class CoroutineDispatcher :
 
     public final override fun releaseInterceptedContinuation(continuation: Continuation<*>) {
         /*
-         * Unconditional cast is safe here: we only return DispatchedContinuation from `interceptContinuation`,
+         * Unconditional cast is safe here: we return only DispatchedContinuation from `interceptContinuation`,
          * any ClassCastException can only indicate compiler bug
          */
         val dispatched = continuation as DispatchedContinuation<*>
@@ -229,4 +261,3 @@ public abstract class CoroutineDispatcher :
     /** @suppress for nicer debugging */
     override fun toString(): String = "$classSimpleName@$hexAddress"
 }
-

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

@@ -24,15 +24,7 @@ public enum class CoroutineStart {
     /**
      * Immediately schedules the coroutine for execution according to its context. This is usually the default option.
      *
-     * The behavior of [DEFAULT] depends on the result of [CoroutineDispatcher.isDispatchNeeded] in
-     * the context of the started coroutine.
-     * - In the typical case where a dispatch is needed, the coroutine is dispatched for execution on that dispatcher.
-     *   It may take a while for the dispatcher to start the task; the thread that invoked the coroutine builder
-     *   does not wait for the task to start and instead continues its execution.
-     * - If no dispatch is needed (which is the case for [Dispatchers.Main.immediate][MainCoroutineDispatcher.immediate]
-     *   when already on the main thread and for [Dispatchers.Unconfined]),
-     *   the task is executed immediately in the same thread that invoked the coroutine builder,
-     *   similarly to [UNDISPATCHED].
+     * [DEFAULT] uses the default dispatch procedure described in the [CoroutineDispatcher] documentation.
      *
      * If the coroutine's [Job] is cancelled before it started executing, then it will not start its
      * execution at all and will be considered [cancelled][Job.isCancelled].
@@ -91,7 +83,8 @@ public enum class CoroutineStart {
      * Starting a coroutine with [LAZY] only creates the coroutine, but does not schedule it for execution.
      * When the completion of the coroutine is first awaited
      * (for example, via [Job.join]) or explicitly [started][Job.start],
-     * the dispatch procedure described in [DEFAULT] happens in the thread that did it.
+     * the dispatch procedure described in the [CoroutineDispatcher] documentation is performed in the thread
+     * that did it.
      *
      * The details of what counts as waiting can be found in the documentation of the corresponding coroutine builders
      * like [launch][CoroutineScope.launch] and [async][CoroutineScope.async].
@@ -229,6 +222,7 @@ public enum class CoroutineStart {
      * - Resumptions from later suspensions will properly use the actual dispatcher from the coroutine's context.
      *   Only the code until the first suspension point will be executed immediately.
      * - Even if the coroutine was cancelled already, its code will still start to be executed, similar to [ATOMIC].
+     * - The coroutine will not form an event loop. See [Dispatchers.Unconfined] for an explanation of event loops.
      *
      * This set of behaviors makes [UNDISPATCHED] well-suited for cases where the coroutine has a distinct
      * initialization phase whose side effects we want to rely on later.