Skip to content

Commit be781c5

Browse files
authored
Use dashes instead of asterisks for lists in KDoc (#4027)
* Replace `*` with `-` everywhere in KDoc git grep -l '\* \+\* ' | xargs -n1 sed -i 's/^\([ \t]*\* \+\)\* /\1- /' * Fix several false positives of the regex replacement
1 parent 2b69cf0 commit be781c5

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+218
-218
lines changed

buildSrc/src/main/kotlin/CommunityProjectsBuild.kt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@ private val LOGGER: Logger = Logger.getLogger("Kotlin settings logger")
1717
* are compatible with our libraries (aka "integration testing that substitutes lack of unit testing").
1818
*
1919
* When `build_snapshot_train` is set to true (and [isSnapshotTrainEnabled] returns `true`),
20-
* * `kotlin_version property` is overridden with `kotlin_snapshot_version` (see [getOverriddenKotlinVersion]),
21-
* * `atomicfu_version` is overwritten by TeamCity environment (AFU is built with snapshot and published to mavenLocal
20+
* - `kotlin_version property` is overridden with `kotlin_snapshot_version` (see [getOverriddenKotlinVersion]),
21+
* - `atomicfu_version` is overwritten by TeamCity environment (AFU is built with snapshot and published to mavenLocal
2222
* as previous step or the snapshot build).
2323
* Additionally, mavenLocal and Sonatype snapshots are added to repository list and stress tests are disabled
2424
* (see [configureCommunityBuildTweaks]).

integration/kotlinx-coroutines-play-services/src/Tasks.kt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,8 @@ public fun <T> Task<T>.asDeferred(): Deferred<T> = asDeferredImpl(null)
4444
/**
4545
* Converts this task to an instance of [Deferred] with a [CancellationTokenSource] to control cancellation.
4646
* The cancellation of this function is bi-directional:
47-
* * If the given task is cancelled, the resulting deferred will be cancelled.
48-
* * If the resulting deferred is cancelled, the provided [cancellationTokenSource] will be cancelled.
47+
* - If the given task is cancelled, the resulting deferred will be cancelled.
48+
* - If the resulting deferred is cancelled, the provided [cancellationTokenSource] will be cancelled.
4949
*
5050
* Providing a [CancellationTokenSource] that is unrelated to the receiving [Task] is not supported and
5151
* leads to an unspecified behaviour.
@@ -105,9 +105,9 @@ public suspend fun <T> Task<T>.await(): T = awaitImpl(null)
105105
* Awaits the completion of the task that is linked to the given [CancellationTokenSource] to control cancellation.
106106
*
107107
* This suspending function is cancellable and cancellation is bi-directional:
108-
* * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
108+
* - If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
109109
* cancels the [cancellationTokenSource] and throws a [CancellationException].
110-
* * If the task is cancelled, then this function will throw a [CancellationException].
110+
* - If the task is cancelled, then this function will throw a [CancellationException].
111111
*
112112
* Providing a [CancellationTokenSource] that is unrelated to the receiving [Task] is not supported and
113113
* leads to an unspecified behaviour.

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

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,10 @@ import kotlin.coroutines.*
1616
*
1717
* The following methods are available for override:
1818
*
19-
* * [onStart] is invoked when the coroutine was created in non-active state and is being [started][Job.start].
20-
* * [onCancelling] is invoked as soon as the coroutine starts being cancelled for any reason (or completes).
21-
* * [onCompleted] is invoked when the coroutine completes with a value.
22-
* * [onCancelled] in invoked when the coroutine completes with an exception (cancelled).
19+
* - [onStart] is invoked when the coroutine was created in non-active state and is being [started][Job.start].
20+
* - [onCancelling] is invoked as soon as the coroutine starts being cancelled for any reason (or completes).
21+
* - [onCompleted] is invoked when the coroutine completes with a value.
22+
* - [onCancelled] in invoked when the coroutine completes with an exception (cancelled).
2323
*
2424
* @param parentContext the context of the parent coroutine.
2525
* @param initParentJob specifies whether the parent-child relationship should be instantiated directly
@@ -114,10 +114,10 @@ public abstract class AbstractCoroutine<in T>(
114114
* Starts this coroutine with the given code [block] and [start] strategy.
115115
* This function shall be invoked at most once on this coroutine.
116116
*
117-
* * [DEFAULT] uses [startCoroutineCancellable].
118-
* * [ATOMIC] uses [startCoroutine].
119-
* * [UNDISPATCHED] uses [startCoroutineUndispatched].
120-
* * [LAZY] does nothing.
117+
* - [DEFAULT] uses [startCoroutineCancellable].
118+
* - [ATOMIC] uses [startCoroutine].
119+
* - [UNDISPATCHED] uses [startCoroutineUndispatched].
120+
* - [LAZY] does nothing.
121121
*/
122122
public fun <R> start(start: CoroutineStart, receiver: R, block: suspend R.() -> T) {
123123
start(block, receiver, this)

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -259,7 +259,7 @@ public interface CancellableContinuation<in T> : Continuation<T> {
259259
* it can be lost when the coroutine is cancelled. In order to ensure that the resource can be properly closed
260260
* in this case, the [CancellableContinuation] interface provides two functions.
261261
*
262-
* * [invokeOnCancellation][CancellableContinuation.invokeOnCancellation] installs a handler that is called
262+
* - [invokeOnCancellation][CancellableContinuation.invokeOnCancellation] installs a handler that is called
263263
* whenever a suspend coroutine is being cancelled. In addition to the example at the beginning, it can be
264264
* used to ensure that a resource that was opened before the call to
265265
* `suspendCancellableCoroutine` or in its body is closed in case of cancellation.
@@ -274,7 +274,7 @@ public interface CancellableContinuation<in T> : Continuation<T> {
274274
* }
275275
* ```
276276
*
277-
* * [resume(value) { ... }][CancellableContinuation.resume] method on a [CancellableContinuation] takes
277+
* - [resume(value) { ... }][CancellableContinuation.resume] method on a [CancellableContinuation] takes
278278
* an optional `onCancellation` block. It can be used when resuming with a resource that must be closed by
279279
* the code that called the corresponding suspending function.
280280
*

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -84,11 +84,11 @@ internal open class CancellableContinuationImpl<in T>(
8484
* - installParentHandle publishes this instance on T1
8585
*
8686
* T1 writes:
87-
* * handle = installed; right after the installation
88-
* * Shortly after: if (isComplete) handle = NonDisposableHandle
87+
* - handle = installed; right after the installation
88+
* - Shortly after: if (isComplete) handle = NonDisposableHandle
8989
*
9090
* Any other T writes if the parent job is cancelled in detachChild:
91-
* * handle = NonDisposableHandle
91+
* - handle = NonDisposableHandle
9292
*
9393
* We want to preserve a strict invariant on parentHandle transition, allowing only three of them:
9494
* null -> anyHandle

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@ import kotlinx.coroutines.internal.*
99
* wrapped into [CompletionHandlerException], and rethrown, potentially causing crash of unrelated code.
1010
*
1111
* The meaning of `cause` that is passed to the handler:
12-
* * Cause is `null` when the job has completed normally.
13-
* * Cause is an instance of [CancellationException] when the job was cancelled _normally_.
12+
* - Cause is `null` when the job has completed normally.
13+
* - Cause is an instance of [CancellationException] when the job was cancelled _normally_.
1414
* **It should not be treated as an error**. In particular, it should not be reported to error logs.
15-
* * Otherwise, the job had _failed_.
15+
* - Otherwise, the job had _failed_.
1616
*
1717
* **Note**: This type is a part of internal machinery that supports parent-child hierarchies
1818
* and allows for implementation of suspending functions that wait on the Job's state.

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,18 +9,18 @@ import kotlin.coroutines.*
99
* The following standard implementations are provided by `kotlinx.coroutines` as properties on
1010
* the [Dispatchers] object:
1111
*
12-
* * [Dispatchers.Default] &mdash; is used by all standard builders if no dispatcher or any other [ContinuationInterceptor]
12+
* - [Dispatchers.Default] &mdash; is used by all standard builders if no dispatcher or any other [ContinuationInterceptor]
1313
* is specified in their context. It uses a common pool of shared background threads.
1414
* This is an appropriate choice for compute-intensive coroutines that consume CPU resources.
15-
* * [Dispatchers.IO] &mdash; uses a shared pool of on-demand created threads and is designed for offloading of IO-intensive _blocking_
15+
* - [Dispatchers.IO] &mdash; uses a shared pool of on-demand created threads and is designed for offloading of IO-intensive _blocking_
1616
* operations (like file I/O and blocking socket I/O).
17-
* * [Dispatchers.Unconfined] &mdash; starts coroutine execution in the current call-frame until the first suspension,
17+
* - [Dispatchers.Unconfined] &mdash; starts coroutine execution in the current call-frame until the first suspension,
1818
* whereupon the coroutine builder function returns.
1919
* The coroutine will later resume in whatever thread used by the
2020
* corresponding suspending function, without confining it to any specific thread or pool.
2121
* **The `Unconfined` dispatcher should not normally be used in code**.
22-
* * Private thread pools can be created with [newSingleThreadContext] and [newFixedThreadPoolContext].
23-
* * An arbitrary [Executor][java.util.concurrent.Executor] can be converted to a dispatcher with the [asCoroutineDispatcher] extension function.
22+
* - Private thread pools can be created with [newSingleThreadContext] and [newFixedThreadPoolContext].
23+
* - An arbitrary [Executor][java.util.concurrent.Executor] can be converted to a dispatcher with the [asCoroutineDispatcher] extension function.
2424
*
2525
* This class ensures that debugging facilities in [newCoroutineContext] function work properly.
2626
*/

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,9 +81,9 @@ public inline fun CoroutineExceptionHandler(crossinline handler: (CoroutineConte
8181
* ### Uncaught exceptions with no handler
8282
*
8383
* When no handler is installed, exception are handled in the following way:
84-
* * If exception is [CancellationException], it is ignored, as these exceptions are used to cancel coroutines.
85-
* * Otherwise, if there is a [Job] in the context, then [Job.cancel] is invoked.
86-
* * Otherwise, as a last resort, the exception is processed in a platform-specific manner:
84+
* - If exception is [CancellationException], it is ignored, as these exceptions are used to cancel coroutines.
85+
* - Otherwise, if there is a [Job] in the context, then [Job.cancel] is invoked.
86+
* - Otherwise, as a last resort, the exception is processed in a platform-specific manner:
8787
* - On JVM, all instances of [CoroutineExceptionHandler] found via [ServiceLoader], as well as
8888
* the current thread's [Thread.uncaughtExceptionHandler], are invoked.
8989
* - On Native, the whole application crashes with the exception.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,9 @@ import kotlin.coroutines.intrinsics.*
4242
* responsible for launching child coroutines. The corresponding instance of `CoroutineScope` shall be created
4343
* with either `CoroutineScope()` or `MainScope()`:
4444
*
45-
* * `CoroutineScope()` uses the [context][CoroutineContext] provided to it as a parameter for its coroutines
45+
* - `CoroutineScope()` uses the [context][CoroutineContext] provided to it as a parameter for its coroutines
4646
* and adds a [Job] if one is not provided as part of the context.
47-
* * `MainScope()` uses [Dispatchers.Main] for its coroutines and has a [SupervisorJob].
47+
* - `MainScope()` uses [Dispatchers.Main] for its coroutines and has a [SupervisorJob].
4848
*
4949
* **The key part of custom usage of `CoroutineScope` is cancelling it at the end of the lifecycle.**
5050
* The [CoroutineScope.cancel] extension function shall be used when the entity that was launching coroutines

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

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@ import kotlin.coroutines.*
99
* It is used in `start` parameter of [launch][CoroutineScope.launch], [async][CoroutineScope.async], and other coroutine builder functions.
1010
*
1111
* The summary of coroutine start options is:
12-
* * [DEFAULT] -- immediately schedules coroutine for execution according to its context;
13-
* * [LAZY] -- starts coroutine lazily, only when it is needed;
14-
* * [ATOMIC] -- atomically (in a non-cancellable way) schedules coroutine for execution according to its context;
15-
* * [UNDISPATCHED] -- immediately executes coroutine until its first suspension point _in the current thread_.
12+
* - [DEFAULT] -- immediately schedules coroutine for execution according to its context;
13+
* - [LAZY] -- starts coroutine lazily, only when it is needed;
14+
* - [ATOMIC] -- atomically (in a non-cancellable way) schedules coroutine for execution according to its context;
15+
* - [UNDISPATCHED] -- immediately executes coroutine until its first suspension point _in the current thread_.
1616
*/
1717
public enum class CoroutineStart {
1818
/**
@@ -75,10 +75,10 @@ public enum class CoroutineStart {
7575
/**
7676
* Starts the corresponding block with receiver as a coroutine with this coroutine start strategy.
7777
*
78-
* * [DEFAULT] uses [startCoroutineCancellable].
79-
* * [ATOMIC] uses [startCoroutine].
80-
* * [UNDISPATCHED] uses [startCoroutineUndispatched].
81-
* * [LAZY] does nothing.
78+
* - [DEFAULT] uses [startCoroutineCancellable].
79+
* - [ATOMIC] uses [startCoroutine].
80+
* - [UNDISPATCHED] uses [startCoroutineUndispatched].
81+
* - [LAZY] does nothing.
8282
*
8383
* @suppress **This an internal API and should not be used from general code.**
8484
*/

0 commit comments

Comments
 (0)