Repository: Kotlin/kotlinx.coroutines
File: kotlinx-coroutines-core/common/src/CoroutineStart.kt (Kotlin)

Code before:
package kotlinx.coroutines

import kotlinx.coroutines.intrinsics.*
import kotlin.coroutines.*

/**
 * Defines start options for coroutines builders.
 *
 * It is used in the `start` parameter of coroutine builder functions like
 * [launch][CoroutineScope.launch] and [async][CoroutineScope.async]
 * to describe when and how the coroutine should be dispatched initially.
 *
 * This parameter only affects how the coroutine behaves until it reaches the first suspension point.
 * After that, cancellability and dispatching depend on the implementation details of the invoked suspending functions.
 * Use [suspendCancellableCoroutine] to implement custom cancellable suspending functions.
 *
 * The summary of coroutine start options is:
 * - [DEFAULT] immediately schedules the coroutine for execution according to its context;
 * - [LAZY] starts coroutine lazily, only when it is needed;
 * - [ATOMIC] atomically (in a non-cancellable way) schedules the coroutine for execution according to its context;
 * - [UNDISPATCHED] immediately executes the coroutine until its first suspension point _in the current thread_.
 */
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].
     *
     * If the coroutine's [Job] is cancelled before it started executing, then it will not start its
     * execution at all, and will instead complete with an exception.
     *
     * Comparisons with the other options:
     * - [LAZY] delays the moment of the initial dispatch until the completion of the coroutine is awaited.
     * - [ATOMIC] prevents the coroutine from being cancelled before its first suspension point.
     * - [UNDISPATCHED] always executes the coroutine until the first suspension immediately in the same thread
     *   (as if [CoroutineDispatcher.isDispatchNeeded] returned `false`),

Review comment (suggestion):
```suggestion
 * - [LAZY] starts coroutine lazily, only when its result is needed;
```

might be a bit better up to you, we elaborate on that below anyway

Code after:
package kotlinx.coroutines

import kotlinx.coroutines.intrinsics.*
import kotlin.coroutines.*

/**
 * Defines start options for coroutines builders.
 *
 * It is used in the `start` parameter of coroutine builder functions like
 * [launch][CoroutineScope.launch] and [async][CoroutineScope.async]
 * to describe when and how the coroutine should be dispatched initially.
 *
 * This parameter only affects how the coroutine behaves until the code of its body starts executing.
 * After that, cancellability and dispatching are defined by the behavior of the invoked suspending functions.
 *
 * The summary of coroutine start options is:
 * - [DEFAULT] immediately schedules the coroutine for execution according to its context.
 * - [LAZY] delays the moment of the initial dispatch until the result of the coroutine is needed.
 * - [ATOMIC] prevents the coroutine from being cancelled before it starts, ensuring that its code will start
 *   executing in any case.
 * - [UNDISPATCHED] immediately executes the coroutine until its first suspension point _in the current thread_.
 */
public enum class CoroutineStart {
    /**
     * Immediately schedules the coroutine for execution according to its context. This is usually the default option.
     *
     * [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].
     *
     * Examples:
     *
     * ```
     * // Example of starting a new coroutine that goes through a dispatch
     * runBlocking {
     *     println("1. About to start a new coroutine.")
     *     // Dispatch the job to execute later.
     *     // The parent coroutine's dispatcher is inherited by default.
     *     // In this case, it's the single thread backing `runBlocking`.
     *     launch { // CoroutineStart.DEFAULT is launch's default start mode
     *         println("3. When the thread is available, we start the coroutine")
     *     }
     *     println("2. The thread keeps doing other work after launching the coroutine")