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

Code before:
     * ```
     * val notAMutex = Dispatchers.Default.limitedParallelism(1)
     *
     * repeat(3) {
     *     launch(notAMutex) {
     *         println("Coroutine $it entering...")
     *         delay(20.milliseconds)
     *         println("Coroutine $it leaving.")
     *     }
     * }
     * ```
     *
     * The output will be similar to this:
     *
     * ```
     * Coroutine 0 entering...
     * Coroutine 1 entering...
     * Coroutine 2 entering...
     * Coroutine 0 leaving.
     * Coroutine 1 leaving.
     * Coroutine 2 leaving.
     * ```
     *
     * This means that coroutines are not guaranteed to run to completion before the dispatcher starts executing
     * code from another coroutine.
     * The only guarantee in this example is that two `println` calls in several threads simultaneously.
     *
     * Use a [kotlinx.coroutines.sync.Mutex] or a [kotlinx.coroutines.sync.Semaphore] for limiting concurrency.
     *
     * ### Dispatchers.IO
     *
     * `Dispatcher.IO` is considered _elastic_ for the purposes of limited parallelism -- the sum of
     * views is not restricted by the capacity of `Dispatchers.IO`.
     * It means that it is safe to replace `newFixedThreadPoolContext(nThreads)` with
     * `Dispatchers.IO.limitedParallelism(nThreads)` w.r.t. available number of threads.
     * See `Dispatchers.IO` documentation for more details.
     *
     * ### Restrictions and implementation details
     *
     * The default implementation of `limitedParallelism` does not support direct dispatchers,
     * such as executing the given runnable in place during [dispatch] calls.
     * Any dispatcher that may return `false` from [isDispatchNeeded] is considered direct.
     * For direct dispatchers, it is recommended to override this method
     * and provide a domain-specific implementation or to throw an [UnsupportedOperationException].
     *
     * Implementations of this method are allowed to return `this` if the current dispatcher already satisfies the parallelism requirement.
     * For example, `Dispatchers.Main.limitedParallelism(1)` returns `Dispatchers.Main`, because the main dispatcher is already single-threaded.
     *
     * @param name optional name for the resulting dispatcher string representation if a new dispatcher was created.
     *        Implementations are free to ignore this parameter.
     * @throws IllegalArgumentException if the given [parallelism] is non-positive

Review comment (suggestion):
Seems to be missing a few words
```suggestion
     * The only guarantee in this example is that two `println` calls will not occur in several threads simultaneously.
```

Code after:
     * ```
     * val notAMutex = Dispatchers.Default.limitedParallelism(1)
     *
     * repeat(3) {
     *     launch(notAMutex) {
     *         println("Coroutine $it entering...")
     *         delay(20.milliseconds)
     *         println("Coroutine $it leaving.")
     *     }
     * }
     * ```
     *
     * The output will be similar to this:
     *
     * ```
     * Coroutine 0 entering...
     * Coroutine 1 entering...
     * Coroutine 2 entering...
     * Coroutine 0 leaving.
     * Coroutine 1 leaving.
     * Coroutine 2 leaving.
     * ```
     *
     * This means that coroutines are not guaranteed to run to completion before the dispatcher starts executing
     * code from another coroutine.
     * The only guarantee in this example is that two `println` calls will not occur in several threads simultaneously.
     *
     * Use a [kotlinx.coroutines.sync.Mutex] or a [kotlinx.coroutines.sync.Semaphore] for limiting concurrency.
     *
     * ### Dispatchers.IO
     *
     * `Dispatcher.IO` is considered _elastic_ for the purposes of limited parallelism -- the sum of
     * views is not restricted by the capacity of `Dispatchers.IO`.
     * It means that it is safe to replace `newFixedThreadPoolContext(nThreads)` with
     * `Dispatchers.IO.limitedParallelism(nThreads)` w.r.t. available number of threads.
     * See `Dispatchers.IO` documentation for more details.
     *
     * ### Restrictions and implementation details
     *
     * The default implementation of `limitedParallelism` does not support direct dispatchers,
     * such as executing the given runnable in place during [dispatch] calls.
     * Any dispatcher that may return `false` from [isDispatchNeeded] is considered direct.
     * For direct dispatchers, it is recommended to override this method
     * and provide a domain-specific implementation or to throw an [UnsupportedOperationException].
     *
     * Implementations of this method are allowed to return `this` if the current dispatcher already satisfies the parallelism requirement.
     * For example, `Dispatchers.Main.limitedParallelism(1)` returns `Dispatchers.Main`, because the main dispatcher is already single-threaded.
     *
     * @param name optional name for the resulting dispatcher string representation if a new dispatcher was created.
     *        Implementations are free to ignore this parameter.
     * @throws IllegalArgumentException if the given [parallelism] is non-positive