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

Code before:
     * ```
     * // Example of lazily starting a new coroutine that doesn't go through a dispatch initially
     * runBlocking {
     *     println("1. About to lazily start a new coroutine.")
     *     // Create a job to execute on `Dispatchers.Unconfined` later.
     *     val lazyJob = launch(Dispatchers.Unconfined, start = CoroutineStart.LAZY) {
     *         println("3. The coroutine starts on the thread that called `join`.")
     *     }
     *     // We start the job on another thread for illustrative purposes
     *     launch(Dispatchers.Default) {
     *         println("2. We start the lazyJob.")
     *         job.start() // runs lazyJob's code in-place
     *         println("4. Only now does the `start` call return.")
     *     }
     * }
     * ```
     */
    LAZY,

    /**
     * Atomically (i.e., in a non-cancellable way) schedules the coroutine for execution according to its context.
     *
     * This is similar to [DEFAULT], but the coroutine is guaranteed to start executing even if it was cancelled.
     * This only affects the initial portion of the code: on subsequent suspensions, cancellation will work as usual.
     *
     * [UNDISPATCHED] also ensures that coroutines will be started in any case.
     * The difference is that, instead of immediately starting them on the same thread,
     * [ATOMIC] performs the full dispatch procedure just as [DEFAULT] does.
     *
     * Because of this, we can use [ATOMIC] in cases where we want to be certain that some code eventually runs
     * and uses a specific dispatcher to do that.
     *
     * Example:
     * ```
     * val N_PERMITS = 3
     * val semaphore = Semaphore(N_PERMITS)
     * try {
     *     repeat(100) {
     *         semaphore.acquire()
     *         if (it != 7) {
     *             println("Scheduling $it...")
     *         } else {
     *             // "randomly" cancel the whole procedure
     *             cancel()
     *         }
     *         launch(Dispatchers.Default, start = CoroutineStart.ATOMIC) {
     *             println("Entered $it")
     *             try {
     *                 println("Performing the procedure $it")
     *                 delay(10.milliseconds)
     *                 println("Done with the procedure $it")

Review comment (refactor):
I'd say this is redundant as it looks like a typo: I read the doc to `ATOMIC` and it mentions `UNDISPATCHED` in the form that might imply this is a doc to `UNDISPATCHED`.

Let's remove this section altogether, we have undispatched explained nearby anyway

Code after:
     *         println("4. Only now does the `start` call return.")
     *     }
     * }
     * ```
     *
     * ## Alternatives
     *
     * The effects of [LAZY] can usually be achieved more idiomatically without it.
     *
     * When a coroutine is started with [LAZY] and is stored in a property,
     * it may be a better choice to use [lazy] instead:
     *
     * ```
     * // instead of `val page = scope.async(start = CoroutineStart.LAZY) { getPage() }`, do
     * val page by lazy { scope.async { getPage() } }
     * ```
     *
     * This way, the child coroutine is not created at all unless it is needed.
     * Note that with this, any access to this variable will start the coroutine,
     * even something like `page.invokeOnCompletion { }` or `page.isActive`.
     *
     * If a coroutine is started with [LAZY] and then unconditionally started,
     * it is more idiomatic to create the coroutine in the exact place where it is started:
     *
     * ```
     * // instead of `val job = scope.launch(start = CoroutineStart.LAZY) { }; job.start()`, do
     * scope.launch { }
     * ```
     */
    LAZY,

    /**
     * Atomically (i.e., in a non-cancellable way) schedules the coroutine for execution according to its context.
     *
     * This is similar to [DEFAULT], but the coroutine is guaranteed to start executing even if it was cancelled.
     * This only affects the behavior until the body of the coroutine starts executing;
     * inside the body, cancellation will work as usual.
     *
     * Like [ATOMIC], [UNDISPATCHED], too, ensures that coroutines will be started in any case.
     * The difference is that, instead of immediately starting them on the same thread,
     * [ATOMIC] performs the full dispatch procedure just as [DEFAULT] does.
     *
     * Because of this, we can use [ATOMIC] in cases where we want to be certain that some code eventually runs
     * and uses a specific dispatcher to do that.
     *
     * Example:
     * ```
     * val mutex = Mutex()
     *
     * mutex.lock() // lock the mutex outside the coroutine
     * // ... // initial portion of the work, protected by the mutex