Use consistent indentation in our documentation (#4122)

Found using `git grep -P '\*    ?[a-zA-Z]'`

---------

Co-authored-by: Dmitry Khalanskiy <Dmitry.Khalanskiy@jetbrains.com>

integration/kotlinx-coroutines-slf4j/src/MDCContext.kt

@@ -33,9 +33,9 @@ public typealias MDCContextMap = Map<String, String>?
  *
  * ```
  * launch(MDCContext()) {
- *    MDC.put("key", "value") // This update will be lost
- *    delay(100)
- *    println(MDC.get("key")) // This will print null
+ *     MDC.put("key", "value") // This update will be lost
+ *     delay(100)
+ *     println(MDC.get("key")) // This will print null
  * }
  * ```
  *

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

@@ -274,11 +274,11 @@ internal fun <T> CancellableContinuation<T>.invokeOnCancellation(handler: Cancel
  *
  * ```
  * suspendCancellableCoroutine { continuation ->
- *    val resource = openResource() // Opens some resource
- *    continuation.invokeOnCancellation {
- *        resource.close() // Ensures the resource is closed on cancellation
- *    }
- *    // ...
+ *     val resource = openResource() // Opens some resource
+ *     continuation.invokeOnCancellation {
+ *         resource.close() // Ensures the resource is closed on cancellation
+ *     }
+ *     // ...
  * }
  * ```
  *

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

@@ -366,7 +366,7 @@ internal open class CancellableContinuationImpl<in T>(
      *
      * ```
      * invokeOnCancellation { cause ->
-     *   segment.onCancellation(index, cause)
+     *     segment.onCancellation(index, cause)
      * }
      * ```
      */

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

@@ -13,11 +13,11 @@ internal expect fun assert(value: () -> Boolean)
  * ```
  * class BadResponseCodeException(val responseCode: Int) : Exception(), CopyableThrowable<BadResponseCodeException> {
  *
- *  override fun createCopy(): BadResponseCodeException {
- *    val result = BadResponseCodeException(responseCode)
- *    result.initCause(this)
- *    return result
- *  }
+ *     override fun createCopy(): BadResponseCodeException {
+ *         val result = BadResponseCodeException(responseCode)
+ *         result.initCause(this)
+ *         return result
+ *     }
  * ```
  *
  * Copy mechanism is used only on JVM, but it might be convenient to implement it in common exceptions,

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

@@ -51,10 +51,10 @@ public interface Deferred<out T> : Job {
      * The following idiom may be helpful to avoid this:
      * ```
      * try {
-     *    deferred.await()
+     *     deferred.await()
      * } catch (e: CancellationException) {
-     *    currentCoroutineContext().ensureActive() // throws if the current coroutine was cancelled
-     *    processException(e) // if this line executes, the exception is the result of `await` itself
+     *     currentCoroutineContext().ensureActive() // throws if the current coroutine was cancelled
+     *     processException(e) // if this line executes, the exception is the result of `await` itself
      * }
      * ```
      *

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

@@ -52,11 +52,11 @@ public expect object Dispatchers {
      * For example, the following code:
      * ```
      * withContext(Dispatchers.Unconfined) {
-     *    println(1)
-     *    launch(Dispatchers.Unconfined) { // Nested unconfined
-     *        println(2)
-     *    }
-     *    println(3)
+     *     println(1)
+     *     launch(Dispatchers.Unconfined) { // Nested unconfined
+     *         println(2)
+     *     }
+     *     println(3)
      * }
      * println("Done")
      * ```

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

@@ -21,17 +21,17 @@ public abstract class MainCoroutineDispatcher : CoroutineDispatcher() {
      * Example of usage:
      * ```
      * suspend fun updateUiElement(val text: String) {
-     *   /*
-     *    * If it is known that updateUiElement can be invoked both from the Main thread and from other threads,
-     *    * `immediate` dispatcher is used as a performance optimization to avoid unnecessary dispatch.
-     *    *
-     *    * In that case, when `updateUiElement` is invoked from the Main thread, `uiElement.text` will be
-     *    * invoked immediately without any dispatching, otherwise, the `Dispatchers.Main` dispatch cycle will be triggered.
-     *    */
-     *   withContext(Dispatchers.Main.immediate) {
-     *     uiElement.text = text
-     *   }
-     *   // Do context-independent logic such as logging
+     *     /*
+     *      * If it is known that updateUiElement can be invoked both from the Main thread and from other threads,
+     *      * `immediate` dispatcher is used as a performance optimization to avoid unnecessary dispatch.
+     *      *
+     *      * In that case, when `updateUiElement` is invoked from the Main thread, `uiElement.text` will be
+     *      * invoked immediately without any dispatching, otherwise, the `Dispatchers.Main` dispatch cycle will be triggered.
+     *      */
+     *     withContext(Dispatchers.Main.immediate) {
+     *         uiElement.text = text
+     *     }
+     *     // Do context-independent logic such as logging
      * }
      * ```
      *

kotlinx-coroutines-core/common/src/channels/Channel.kt

@@ -116,12 +116,12 @@ public interface SendChannel<in E> {
      * ```
      * val events = Channel<Event>(UNLIMITED)
      * callbackBasedApi.registerCallback { event ->
-     *   events.trySend(event)
-     *       .onClosed { /* channel is already closed, but the callback hasn't stopped yet */ }
+     *     events.trySend(event)
+     *         .onClosed { /* channel is already closed, but the callback hasn't stopped yet */ }
      * }
      *
      * val uiUpdater = uiScope.launch(Dispatchers.Main) {
-     *    events.consume { /* handle events */ }
+     *     events.consume { /* handle events */ }
      * }
      * // Stop the callback after the channel is closed or cancelled
      * events.invokeOnClose { callbackBasedApi.stop() }
@@ -145,7 +145,7 @@ public interface SendChannel<in E> {
      * It has proven itself as the most error-prone method in Channel API:
      *
      * - `Boolean` return type creates the false sense of security, implying that `false`
-     *    is returned instead of throwing an exception.
+     *   is returned instead of throwing an exception.
      * - It was used mostly from non-suspending APIs where CancellationException triggered
      *   internal failures in the application (the most common source of bugs).
      * - Due to signature and explicit `if (ch.offer(...))` checks it was easy to
@@ -323,7 +323,7 @@ public interface ReceiveChannel<out E> {
      * It has proven itself as error-prone method in Channel API:
      *
      * - Nullable return type creates the false sense of security, implying that `null`
-     *    is returned instead of throwing an exception.
+     *   is returned instead of throwing an exception.
      * - It was used mostly from non-suspending APIs where CancellationException triggered
      *   internal failures in the application (the most common source of bugs).
      * - Its name was not aligned with the rest of the API and tried to mimic Java's queue instead.

kotlinx-coroutines-core/common/src/flow/Flow.kt

@@ -102,13 +102,13 @@ import kotlin.coroutines.*
  *
  * ```
  * val myFlow = flow {
- *    // GlobalScope.launch { // is prohibited
- *    // launch(Dispatchers.IO) { // is prohibited
- *    // withContext(CoroutineName("myFlow")) { // is prohibited
- *    emit(1) // OK
- *    coroutineScope {
- *        emit(2) // OK -- still the same coroutine
- *    }
+ *     // GlobalScope.launch { // is prohibited
+ *     // launch(Dispatchers.IO) { // is prohibited
+ *     // withContext(CoroutineName("myFlow")) { // is prohibited
+ *     emit(1) // OK
+ *     coroutineScope {
+ *         emit(2) // OK -- still the same coroutine
+ *     }
  * }
  * ```
  *
@@ -119,11 +119,11 @@ import kotlin.coroutines.*
  *
  * If you are looking for performance and are sure that no concurrent emits and context jumps will happen,
  * the [flow] builder can be used alongside a [coroutineScope] or [supervisorScope] instead:
- *  - Scoped primitive should be used to provide a [CoroutineScope].
- *  - Changing the context of emission is prohibited, no matter whether it is `withContext(ctx)` or
- *    a builder argument (e.g. `launch(ctx)`).
- *  - Collecting another flow from a separate context is allowed, but it has the same effect as
- *    applying the [flowOn] operator to that flow, which is more efficient.
+ * - Scoped primitive should be used to provide a [CoroutineScope].
+ * - Changing the context of emission is prohibited, no matter whether it is `withContext(ctx)` or
+ *   a builder argument (e.g. `launch(ctx)`).
+ * - Collecting another flow from a separate context is allowed, but it has the same effect as
+ *   applying the [flowOn] operator to that flow, which is more efficient.
  *
  * ### Exception transparency
  *

kotlinx-coroutines-core/common/src/flow/SharedFlow.kt

@@ -86,11 +86,11 @@ import kotlin.jvm.*
  * It has the following important differences:
  *
  * - `SharedFlow` is simpler, because it does not have to implement all the [Channel] APIs, which allows
- *    for faster and simpler implementation.
+ *   for faster and simpler implementation.
  * - `SharedFlow` supports configurable replay and buffer overflow strategy.
  * - `SharedFlow` has a clear separation into a read-only `SharedFlow` interface and a [MutableSharedFlow].
  * - `SharedFlow` cannot be closed like `BroadcastChannel` and can never represent a failure.
- *    All errors and completion signals should be explicitly _materialized_ if needed.
+ *   All errors and completion signals should be explicitly _materialized_ if needed.
  *
  * To migrate [BroadcastChannel] usage to [SharedFlow], start by replacing usages of the `BroadcastChannel(capacity)`
  * constructor with `MutableSharedFlow(0, extraBufferCapacity=capacity)` (broadcast channel does not replay
@@ -138,7 +138,7 @@ public interface SharedFlow<out T> : Flow<T> {
      * ```
      * val flow = MutableSharedFlow<Int>()
      * launch(start = CoroutineStart.UNDISPATCHED) {
-     *   flow.collect { println(1) }
+     *     flow.collect { println(1) }
      * }
      * flow.emit(1)
      * ```

kotlinx-coroutines-core/common/src/flow/StateFlow.kt

@@ -90,12 +90,12 @@ import kotlin.coroutines.*
  *   for faster, garbage-free implementation, unlike `ConflatedBroadcastChannel` implementation that
  *   allocates objects on each emitted value.
  * - `StateFlow` always has a value which can be safely read at any time via [value] property.
- *    Unlike `ConflatedBroadcastChannel`, there is no way to create a state flow without a value.
+ *   Unlike `ConflatedBroadcastChannel`, there is no way to create a state flow without a value.
  * - `StateFlow` has a clear separation into a read-only `StateFlow` interface and a [MutableStateFlow].
  * - `StateFlow` conflation is based on equality like [distinctUntilChanged] operator,
- *    unlike conflation in `ConflatedBroadcastChannel` that is based on reference identity.
+ *   unlike conflation in `ConflatedBroadcastChannel` that is based on reference identity.
  * - `StateFlow` cannot be closed like `ConflatedBroadcastChannel` and can never represent a failure.
- *    All errors and completion signals should be explicitly _materialized_ if needed.
+ *   All errors and completion signals should be explicitly _materialized_ if needed.
  *
  * `StateFlow` is designed to better cover typical use-cases of keeping track of state changes in time, taking
  * more pragmatic design choices for the sake of convenience.

kotlinx-coroutines-core/common/src/flow/operators/Merge.kt

@@ -92,11 +92,11 @@ public fun <T> Iterable<Flow<T>>.merge(): Flow<T> {
     /*
      * This is a fuseable implementation of the following operator:
      * channelFlow {
-     *    forEach { flow ->
-     *        launch {
-     *            flow.collect { send(it) }
-     *        }
-     *    }
+     *     forEach { flow ->
+     *         launch {
+     *             flow.collect { send(it) }
+     *         }
+     *     }
      * }
      */
     return ChannelLimitedFlowMerge(this)

kotlinx-coroutines-core/common/src/selects/Select.kt

@@ -525,7 +525,7 @@ internal open class SelectImplementation<R>(
      *
      * ```
      * disposeOnCompletion {
-     *   segment.onCancellation(index, null)
+     *     segment.onCancellation(index, null)
      * }
      * ```
      */

kotlinx-coroutines-core/jvm/src/EventLoop.kt

@@ -59,11 +59,11 @@ internal actual inline fun platformAutoreleasePool(crossinline block: () -> Unit
  *
  * ### Invariants
  *
- *  - When invoked from [Dispatchers.Default] **thread** (even if the actual context is different dispatcher,
- *    [CoroutineDispatcher.limitedParallelism] or any in-place wrapper), it runs an arbitrary task that ended
- *    up being scheduled to [Dispatchers.Default] or its counterpart. Tasks scheduled to [Dispatchers.IO]
- *    **are not** executed[1].
- *  - When invoked from [Dispatchers.IO] thread, the same rules apply, but for blocking tasks only.
+ * - When invoked from [Dispatchers.Default] **thread** (even if the actual context is different dispatcher,
+ *   [CoroutineDispatcher.limitedParallelism] or any in-place wrapper), it runs an arbitrary task that ended
+ *   up being scheduled to [Dispatchers.Default] or its counterpart. Tasks scheduled to [Dispatchers.IO]
+ *   **are not** executed[1].
+ * - When invoked from [Dispatchers.IO] thread, the same rules apply, but for blocking tasks only.
  *
  * [1] -- this is purely technical limitation: the scheduler does not have "notify me when CPU token is available" API,
  * and we cannot leave this method without leaving thread in its original state.

kotlinx-coroutines-core/jvm/src/ThreadContextElement.kt

@@ -200,10 +200,10 @@ public interface CopyableThreadContextElement<S> : ThreadContextElement<S> {
  * ...
  * println(myThreadLocal.get()) // Prints "null"
  * launch(Dispatchers.Default + myThreadLocal.asContextElement(value = "foo")) {
- *   println(myThreadLocal.get()) // Prints "foo"
- *   withContext(Dispatchers.Main) {
- *     println(myThreadLocal.get()) // Prints "foo", but it's on UI thread
- *   }
+ *     println(myThreadLocal.get()) // Prints "foo"
+ *     withContext(Dispatchers.Main) {
+ *         println(myThreadLocal.get()) // Prints "foo", but it's on UI thread
+ *     }
  * }
  * println(myThreadLocal.get()) // Prints "null"
  * ```
@@ -213,8 +213,8 @@ public interface CopyableThreadContextElement<S> : ThreadContextElement<S> {
  * ```
  * myThreadLocal.set("main")
  * withContext(Dispatchers.Main) {
- *   println(myThreadLocal.get()) // Prints "main"
- *   myThreadLocal.set("UI")
+ *     println(myThreadLocal.get()) // Prints "main"
+ *     myThreadLocal.set("UI")
  * }
  * println(myThreadLocal.get()) // Prints "main", not "UI"
  * ```
@@ -231,13 +231,13 @@ public interface CopyableThreadContextElement<S> : ThreadContextElement<S> {
  * val tl = ThreadLocal.withInitial { "initial" }
  *
  * runBlocking {
- *   println(tl.get()) // Will print "initial"
- *   // Change context
- *   withContext(tl.asContextElement("modified")) {
- *     println(tl.get()) // Will print "modified"
- *   }
- *   // Context is changed again
- *    println(tl.get()) // <- WARN: can print either "modified" or "initial"
+ *     println(tl.get()) // Will print "initial"
+ *     // Change context
+ *     withContext(tl.asContextElement("modified")) {
+ *         println(tl.get()) // Will print "modified"
+ *     }
+ *     // Context is changed again
+ *     println(tl.get()) // <- WARN: can print either "modified" or "initial"
  * }
  * ```
  * to fix this behaviour use `runBlocking(tl.asContextElement())`
@@ -252,10 +252,10 @@ public fun <T> ThreadLocal<T>.asContextElement(value: T = get()): ThreadContextE
  * Example of usage:
  * ```
  * suspend fun processRequest() {
- *   if (traceCurrentRequestThreadLocal.isPresent()) { // Probabilistic tracing
- *      // Do some heavy-weight tracing
- *   }
- *   // Process request regularly
+ *     if (traceCurrentRequestThreadLocal.isPresent()) { // Probabilistic tracing
+ *         // Do some heavy-weight tracing
+ *     }
+ *     // Process request regularly
  * }
  * ```
  */
@@ -269,13 +269,13 @@ public suspend inline fun ThreadLocal<*>.isPresent(): Boolean = coroutineContext
  * E.g. one may use the following method to enforce proper use of the thread locals with coroutines:
  * ```
  * public suspend inline fun <T> ThreadLocal<T>.getSafely(): T {
- *   ensurePresent()
- *   return get()
+ *     ensurePresent()
+ *     return get()
  * }
  *
  * // Usage
  * withContext(...) {
- *   val value = threadLocal.getSafely() // Fail-fast in case of improper context
+ *     val value = threadLocal.getSafely() // Fail-fast in case of improper context
  * }
  * ```
  */