Documentation improvements (#1229)

* Improve MainCoroutineDispatcher.immediate documentation
* Remove obsolete readme and package descriptions
* Clarify possible replacement of onCompletion parameter in produce
* Add paragraph about parent cancellation to async (Mention structured concurrency, but do not explain it there as the term should be easily googlable).

Fixes #1219
Fixes #994 
Fixes #787

Author: qwwdfsad

kotlinx-coroutines-core/README.md

@@ -1,6 +1,6 @@
 # Module kotlinx-coroutines-core
 
-Core primitives to work with coroutines, available on all platforms.
+Core primitives to work with coroutines.
 
 Coroutine builder functions:
 
@@ -84,13 +84,9 @@ Select expression to perform multiple suspending operations simultaneously until
 
 Low-level primitives for finer-grained control of coroutines.
 
-# Package kotlinx.coroutines.timeunit
-
-Optional time unit support for multiplatform projects.
-
 # Package kotlinx.coroutines.test
 
-Components to ease writing unit-tests for code that contains coroutines with delays and timeouts.
+Obsolete and deprecated module to test coroutines. Replaced with `kotlinx-coroutines-test` module.
 
 <!--- MODULE kotlinx-coroutines-core -->
 <!--- INDEX kotlinx.coroutines -->

kotlinx-coroutines-core/common/README.md

@@ -1,6 +1,6 @@
 # Module kotlinx-coroutines-core
 
-Core primitives to work with coroutines.
+Core primitives to work with coroutines available on all platforms.
 
 Coroutine builder functions:
 
@@ -10,7 +10,6 @@ Coroutine builder functions:
 | [async]       | [Deferred]    | [CoroutineScope] | Returns a single value with the future result
 | [produce][kotlinx.coroutines.channels.produce]     | [ReceiveChannel][kotlinx.coroutines.channels.ReceiveChannel] | [ProducerScope][kotlinx.coroutines.channels.ProducerScope]  | Produces a stream of elements
 | [actor][kotlinx.coroutines.channels.actor]     | [SendChannel][kotlinx.coroutines.channels.SendChannel] | [ActorScope][kotlinx.coroutines.channels.ActorScope]  | Processes a stream of messages
-| [runBlocking] | `T`           | [CoroutineScope] | Blocks the thread while the coroutine runs
 
 Coroutine dispatchers implementing [CoroutineDispatcher]:
 
@@ -96,22 +95,13 @@ Select expression to perform multiple suspending operations simultaneously until
 
 Low-level primitives for finer-grained control of coroutines.
 
-# Package kotlinx.coroutines.timeunit
-
-Optional time unit support for multiplatform projects.
-
-# Package kotlinx.coroutines.test
-
-Components to ease writing unit-tests for code that contains coroutines with delays and timeouts.
-
 <!--- MODULE kotlinx-coroutines-core -->
 <!--- INDEX kotlinx.coroutines -->
 [launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/launch.html
 [Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html
 [CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html
 [async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html
 [Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html
-[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html
 [CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html
 [Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-default.html
 [Dispatchers.Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-unconfined.html

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

@@ -60,6 +60,9 @@ public fun CoroutineScope.launch(
 /**
  * Creates a coroutine and returns its future result as an implementation of [Deferred].
  * The running coroutine is cancelled when the resulting deferred is [cancelled][Job.cancel].
+ * The resulting coroutine has a key difference compared with similar primitives in other languages
+ * and frameworks: it cancels the parent job (or outer scope) on failure to enforce *structured concurrency* paradigm.
+ * To change that behaviour, supervising parent ([SupervisorJob] or [supervisorScope]) can be used.
  *
  * Coroutine context is inherited from a [CoroutineScope], additional context elements can be specified with [context] argument.
  * If the context does not have any dispatcher nor any other [ContinuationInterceptor], then [Dispatchers.Default] is used.
@@ -72,8 +75,6 @@ public fun CoroutineScope.launch(
  * the resulting [Deferred] is created in _new_ state. It can be explicitly started with [start][Job.start]
  * function and will be started implicitly on the first invocation of [join][Job.join], [await][Deferred.await] or [awaitAll].
  *
- * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine.
- * @param start coroutine start option. The default value is [CoroutineStart.DEFAULT].
  * @param block the coroutine code.
  */
 public fun <T> CoroutineScope.async(

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

@@ -25,6 +25,9 @@ public abstract class MainCoroutineDispatcher : CoroutineDispatcher() {
      *   /*
      *    * 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

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

@@ -100,8 +100,16 @@ public fun <E> CoroutineScope.produce(
 }
 
 /**
- * @suppress **This an internal API and should not be used from general code.**
- *           onCompletion parameter will be redesigned.
+ * This an internal API and should not be used from general code.**
+ * onCompletion parameter will be redesigned.
+ * If you have to use `onCompletion` operator, please report to https://github.com/Kotlin/kotlinx.coroutines/issues/.
+ * As a temporary solution, [invokeOnCompletion][Job.invokeOnCompletion] can be used instead:
+ * ```
+ * fun <E> ReceiveChannel<E>.myOperator(): ReceiveChannel<E> = GlobalScope.produce(Dispatchers.Unconfined) {
+ *     coroutineContext[Job]?.invokeOnCompletion { consumes() }
+ * }
+ * ```
+ * @suppress
  */
 @InternalCoroutinesApi
 public fun <E> CoroutineScope.produce(

kotlinx-coroutines-core/native/README.md

@@ -40,6 +40,7 @@ public class TestCoroutineExceptionHandler :
 {
     private val _exceptions = mutableListOf<Throwable>()
 
+    /** @suppress **/
     override fun handleException(context: CoroutineContext, exception: Throwable) {
         synchronized(_exceptions) {
             _exceptions += exception

kotlinx-coroutines-test/src/TestCoroutineExceptionHandler.kt

@@ -34,6 +34,10 @@ public sealed class HandlerDispatcher : MainCoroutineDispatcher(), Delay {
      *   /*
      *    * 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 via
+     *    * `Handler.post` will be triggered.
      *    */
      *   withContext(Dispatchers.Main.immediate) {
      *     uiElement.text = text