Various kotlinlang API module reference improvements (#4167)

* Avoid generating documentation for `runTestCoroutine`
    * It is marked with `@InternalCoroutinesApi` and is not supposed to
be available to the library users.

* Update the package descriptions in the documentation
    * Some packages had no description, and some had outdated ones.

* Mention some additional important API entries in the top-level docs
* Remove most of the occurrences of InternalCoroutinesApi from docs

Co-authored-by: Vsevolod Tolstopyatov <[email protected]>

Author: globsterg

kotlinx-coroutines-core/README.md

@@ -13,10 +13,12 @@ Coroutine builder functions:
 
 Coroutine dispatchers implementing [CoroutineDispatcher]:
 
-| **Name**                                                            | **Description**
-| ------------------------------------------------------------------- | ---------------
-| [Dispatchers.Default][kotlinx.coroutines.Dispatchers.Default]       | Confines coroutine execution to a shared pool of background threads
-| [Dispatchers.Unconfined][kotlinx.coroutines.Dispatchers.Unconfined] | Does not confine coroutine execution in any way
+| **Name**                                                                                            | **Description**
+| --------------------------------------------------------------------------------------------------- | ---------------
+| [Dispatchers.Main][kotlinx.coroutines.Dispatchers.Main]                                             | Confines coroutine execution to the UI thread
+| [Dispatchers.Default][kotlinx.coroutines.Dispatchers.Default]                                       | Confines coroutine execution to a shared pool of background threads
+| [Dispatchers.Unconfined][kotlinx.coroutines.Dispatchers.Unconfined]                                 | Does not confine coroutine execution in any way
+| [CoroutineDispatcher.limitedParallelism][kotlinx.coroutines.CoroutineDispatcher.limitedParallelism] | Creates a view of the given dispatcher, limiting the number of tasks executing in parallel
 
 More context elements:
 
@@ -27,10 +29,14 @@ More context elements:
 
 Synchronization primitives for coroutines:
 
-| **Name**                                        | **Suspending functions**                                                                                            | **Description**
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------
-| [Mutex][kotlinx.coroutines.sync.Mutex]          | [lock][kotlinx.coroutines.sync.Mutex.lock]                                                                          | Mutual exclusion 
-| [Channel][kotlinx.coroutines.channels.Channel]  | [send][kotlinx.coroutines.channels.SendChannel.send], [receive][kotlinx.coroutines.channels.ReceiveChannel.receive] | Communication channel (aka queue or exchanger)
+| **Name**                                                                                                                                             | **Suspending functions**                                                                                            | **Description**
+|------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| ---------------
+| [Mutex][kotlinx.coroutines.sync.Mutex]                                                                                                               | [lock][kotlinx.coroutines.sync.Mutex.lock]                                                                          | Mutual exclusion
+| [Semaphore][kotlinx.coroutines.sync.Semaphore]                                                                                                       | [acquire][kotlinx.coroutines.sync.Semaphore.acquire]                                                                | Limiting the maximum concurrency
+| [Channel][kotlinx.coroutines.channels.Channel]                                                                                                       | [send][kotlinx.coroutines.channels.SendChannel.send], [receive][kotlinx.coroutines.channels.ReceiveChannel.receive] | Communication channel (aka queue or exchanger)
+| [Flow](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/)                                         | [collect][kotlinx.coroutines.flow.Flow.collect]                                                                     | Asynchronous stream of values
+
+<!---  Flow direct link is here to workaround MD case-insensitivity -->
 
 Top-level suspending functions:
 
@@ -45,10 +51,27 @@ Top-level suspending functions:
 | [joinAll][kotlinx.coroutines.joinAll]                     | Joins on all given jobs
 
 Cancellation support for user-defined suspending functions is available with [suspendCancellableCoroutine]
-helper function. [NonCancellable] job object is provided to suppress cancellation with 
+helper function.
+The [NonCancellable] job object is provided to suppress cancellation inside the
 `withContext(NonCancellable) {...}` block of code.
 
-[Select][kotlinx.coroutines.selects.select] expression waits for the result of multiple suspending functions simultaneously:
+Ways to construct asynchronous streams of values:
+
+| **Name**                                                              | **Type** | **Description**
+| --------------------------------------------------------------------- | -------- | ---------------
+| [flow][kotlinx.coroutines.flow.flow]                                  | cold     | Runs a generator-style block of code that emits values
+| [flowOf][kotlinx.coroutines.flow.flowOf]                              | cold     | Emits the values passed as arguments
+| [channelFlow][kotlinx.coroutines.flow.channelFlow]                    | cold     | Runs the given code, providing a channel sending to which means emitting from the flow
+| [callbackFlow][kotlinx.coroutines.flow.callbackFlow]                  | cold     | Allows transforming a callback-based API into a flow
+| [ReceiveChannel.consumeAsFlow][kotlinx.coroutines.flow.consumeAsFlow] | hot      | Transforms a channel into a flow, emitting all of the received values to a single subscriber
+| [ReceiveChannel.receiveAsFlow][kotlinx.coroutines.flow.receiveAsFlow] | hot      | Transforms a channel into a flow, distributing the received values among its subscribers
+| [MutableSharedFlow][kotlinx.coroutines.flow.MutableSharedFlow]        | hot      | Allows emitting each value to arbitrarily many subscribers at once
+| [MutableStateFlow][kotlinx.coroutines.flow.MutableStateFlow]          | hot      | Represents mutable state as a flow
+
+A *cold* stream is some process of generating values, and this process is performed separately for each subscriber.
+A *hot* stream uses the same source of values independently of whether there are subscribers.
+
+A [select][kotlinx.coroutines.selects.select] expression waits for the result of multiple suspending functions simultaneously:
 
 | **Receiver**                                                 | **Suspending function**                                         | **Select clause**                                                 | **Non-suspending version**
 | ------------------------------------------------------------ | --------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------
@@ -65,24 +88,36 @@ General-purpose coroutine builders, contexts, and helper functions.
 
 # Package kotlinx.coroutines.sync
 
-Synchronization primitives (mutex).
+Synchronization primitives (mutex and semaphore).
 
 # Package kotlinx.coroutines.channels
 
 Channels &mdash; non-blocking primitives for communicating a stream of elements between coroutines.
 
 # Package kotlinx.coroutines.flow
 
-Flow &mdash; asynchronous cold stream of elements.
+Flow &mdash; asynchronous cold and hot streams of elements.
 
 # Package kotlinx.coroutines.selects
 
-Select expression to perform multiple suspending operations simultaneously until one of them succeeds.
+Select &mdash; expressions that perform multiple suspending operations simultaneously until one of them succeeds.
 
 # Package kotlinx.coroutines.intrinsics
 
 Low-level primitives for finer-grained control of coroutines.
 
+# Package kotlinx.coroutines.future
+
+[JDK 8's `CompletableFuture`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) support.
+
+# Package kotlinx.coroutines.stream
+
+[JDK 8's `Stream`](https://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html) support.
+
+# Package kotlinx.coroutines.time
+
+[JDK 8's `Duration`](https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html) support via additional overloads for existing time-based operators.
+
 <!--- MODULE kotlinx-coroutines-core -->
 <!--- INDEX kotlinx.coroutines -->
 
@@ -93,8 +128,10 @@ Low-level primitives for finer-grained control of coroutines.
 [kotlinx.coroutines.Deferred]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html
 [kotlinx.coroutines.runBlocking]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html
 [CoroutineDispatcher]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html
+[kotlinx.coroutines.Dispatchers.Main]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-main.html
 [kotlinx.coroutines.Dispatchers.Default]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-default.html
 [kotlinx.coroutines.Dispatchers.Unconfined]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-unconfined.html
+[kotlinx.coroutines.CoroutineDispatcher.limitedParallelism]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/limited-parallelism.html
 [kotlinx.coroutines.NonCancellable]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-non-cancellable/index.html
 [kotlinx.coroutines.CoroutineExceptionHandler]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-exception-handler/index.html
 [kotlinx.coroutines.delay]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/delay.html
@@ -112,10 +149,24 @@ Low-level primitives for finer-grained control of coroutines.
 [kotlinx.coroutines.Deferred.await]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/await.html
 [kotlinx.coroutines.Deferred.onAwait]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/on-await.html
 
+<!--- INDEX kotlinx.coroutines.flow -->
+
+[kotlinx.coroutines.flow.Flow.collect]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/collect.html
+[kotlinx.coroutines.flow.flow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow.html
+[kotlinx.coroutines.flow.flowOf]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow-of.html
+[kotlinx.coroutines.flow.channelFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/channel-flow.html
+[kotlinx.coroutines.flow.callbackFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/callback-flow.html
+[kotlinx.coroutines.flow.consumeAsFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/consume-as-flow.html
+[kotlinx.coroutines.flow.receiveAsFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/receive-as-flow.html
+[kotlinx.coroutines.flow.MutableSharedFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-mutable-shared-flow/index.html
+[kotlinx.coroutines.flow.MutableStateFlow]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-mutable-state-flow/index.html
+
 <!--- INDEX kotlinx.coroutines.sync -->
 
 [kotlinx.coroutines.sync.Mutex]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/index.html
 [kotlinx.coroutines.sync.Mutex.lock]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/lock.html
+[kotlinx.coroutines.sync.Semaphore]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-semaphore/index.html
+[kotlinx.coroutines.sync.Semaphore.acquire]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-semaphore/acquire.html
 
 <!--- INDEX kotlinx.coroutines.channels -->
 

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

@@ -124,6 +124,8 @@ public sealed interface SelectBuilder<in R> {
  * 4) the function that specifies how the internal result provided via
  *    [SelectInstance.trySelect] or [SelectInstance.selectInRegistrationPhase]
  *    should be processed in case of this `select` cancellation while dispatching.
+ *
+ * @suppress **This is unstable API, and it is subject to change.**
  */
 @InternalCoroutinesApi
 public sealed interface SelectClause {
@@ -138,6 +140,8 @@ public sealed interface SelectClause {
  * the specified clause object. In case of channels, the registration logic
  * coincides with the plain `send/receive` operation with the only difference that
  * the `select` instance is stored as a waiter instead of continuation.
+ *
+ * @suppress **This is unstable API, and it is subject to change.**
  */
 @InternalCoroutinesApi
 public typealias RegistrationFunction = (clauseObject: Any, select: SelectInstance<*>, param: Any?) -> Unit
@@ -147,6 +151,8 @@ public typealias RegistrationFunction = (clauseObject: Any, select: SelectInstan
  * or [SelectInstance.trySelect] should be processed. For example, both [ReceiveChannel.onReceive] and
  * [ReceiveChannel.onReceiveCatching] clauses perform exactly the same synchronization logic,
  * but differ when the channel has been discovered in the closed or cancelled state.
+ *
+ * @suppress **This is unstable API, and it is subject to change.**
  */
 @InternalCoroutinesApi
 public typealias ProcessResultFunction = (clauseObject: Any, param: Any?, clauseResult: Any?) -> Any?
@@ -156,6 +162,8 @@ public typealias ProcessResultFunction = (clauseObject: Any, param: Any?, clause
  * or [SelectInstance.selectInRegistrationPhase], should be processed in case of this `select`
  * cancellation while dispatching. Unfortunately, we cannot pass this function only in [SelectInstance.trySelect],
  * as [SelectInstance.selectInRegistrationPhase] can be called when the coroutine is already cancelled.
+ *
+ * @suppress **This is unstable API, and it is subject to change.**
  */
 @InternalCoroutinesApi
 public typealias OnCancellationConstructor = (select: SelectInstance<*>, param: Any?, internalResult: Any?) ->

kotlinx-coroutines-core/wasmWasi/src/internal/CoroutineRunner.kt

@@ -3,6 +3,7 @@ package kotlinx.coroutines.internal
 import kotlinx.coroutines.*
 import kotlin.coroutines.*
 
+/** @suppress **This is internal API and it is subject to change.** */
 @InternalCoroutinesApi
 public fun runTestCoroutine(context: CoroutineContext, block: suspend CoroutineScope.() -> Unit) {
     val newContext = GlobalScope.newCoroutineContext(context)
@@ -11,4 +12,4 @@ public fun runTestCoroutine(context: CoroutineContext, block: suspend CoroutineS
     runEventLoop()
     check(coroutine.isCompleted) { "Coroutine $coroutine did not complete, but the system reached quiescence" }
     coroutine.getCompletionExceptionOrNull()?.let { throw it }
-}
+}