MPP: Documentation (readme files)
diff --git a/README.md b/README.md
index 0694c43..c5778c2 100644
--- a/README.md
+++ b/README.md
@@ -4,17 +4,29 @@
[](http://www.apache.org/licenses/LICENSE-2.0)
[ ](https://bintray.com/kotlin/kotlinx/kotlinx.coroutines/0.20)
-Library support for Kotlin coroutines.
+Library support for Kotlin coroutines in
+[Kotlin/JVM](core/README.md) and
+[Kotlin/JS](js/README.md).
This is a companion version for Kotlin 1.2.10 release.
+```kotlin
+launch {
+ delay(1000)
+ println("Hello from Kotlin Coroutine!")
+}
+```
+
## Modules
-* [core](core/README.md) -- core primitives to work with coroutines:
- * `launch`, `async`, `produce`, `actor`, etc coroutine builders;
+* [common](common/README.md) - common coroutines across all backends:
+ * `launch` and `async` coroutine builders;
* `Job` and `Deferred` light-weight future with cancellation support;
- * `CommonPool` and other coroutine contexts;
+ * `delay` and `yield` top-level suspending functions.
+* [js](js/README.md) - Kotlin/JS implementation of common coroutines with `Promise` support.
+* [core](core/README.md) -- Kotlin/JVM implementation of common coroutines with additional features:
+ * `CommonPool` coroutine context (default on JVM);
* `Channel` and `Mutex` communication and synchronization primitives;
- * `delay`, `yield`, etc top-level suspending functions;
+ * `produce` and `actor` coroutine builders;
* `select` expression support and more.
* [reactive](reactive/README.md) -- modules that provide builders and iteration support for various reactive streams libraries:
* Reactive Streams, RxJava 1.x and 2.x and Project Reactor.
@@ -80,6 +92,10 @@
}
```
+### Kotlin/JS
+
+Use `kotlinx-coroutines-core-js` artifact in your dependencies.
+
### ProGuard
In obfuscated code, fields with different types can have the same names,
diff --git a/common/README.md b/common/README.md
new file mode 100644
index 0000000..07dd61b
--- /dev/null
+++ b/common/README.md
@@ -0,0 +1,11 @@
+# Common coroutines core
+
+This directory contains modules that provide `expect` declarations for common coroutines support across
+various platforms for [mutliplatform Kotlin projects](https://kotlinlang.org/docs/reference/multiplatform.html).
+Note, that documentation is currently provided in platform-specific modules only.
+Module name below corresponds to the artifact name in Maven/Gradle.
+
+## Modules
+
+* [kotlinx-coroutines-core-common](kotlinx-coroutines-core-common/README.md) -- common declarations for coroutine builders and primitives.
+
diff --git a/common/kotlinx-coroutines-core-common/README.md b/common/kotlinx-coroutines-core-common/README.md
new file mode 100644
index 0000000..9bdcfb3
--- /dev/null
+++ b/common/kotlinx-coroutines-core-common/README.md
@@ -0,0 +1,44 @@
+# Module kotlinx-coroutines-core-js
+
+Common primitives to work with coroutines in
+[mutliplatform Kotlin projects](https://kotlinlang.org/docs/reference/multiplatform.html).
+
+Note, that documentation is currently provided in platform-specific modules only:
+* [kotlinx-coroutines-core](../../core/kotlinx-coroutines-core/README.md) for Kotlin/JVM.
+* [kotlinx-coroutines-core-js](../../js/kotlinx-coroutines-core-js/README.md) for Kotlin/JS.
+
+Coroutine builder functions:
+
+| **Name** | **Result** | **Scope** | **Description**
+| ------------- | ------------- | ---------------- | ---------------
+| `launch` | `Job` | `CoroutineScope` | Launches coroutine that does not have any result
+| `async` | `Deferred` | `CoroutineScope` | Returns a single value with the future result
+| `runBlocking` | `T` | `CoroutineScope` | Blocks the event loop while the coroutine runs
+
+Coroutine dispatchers implementing `CoroutineDispatcher`:
+
+| **Name** | **Description**
+| --------------------------- | ---------------
+| `DefaultDispatcher` | Platform-specific default dispatcher
+| `Unconfined` | Does not confine coroutine execution in any way
+
+More context elements:
+
+| **Name** | **Description**
+| --------------------------- | ---------------
+| `NonCancellable` | A non-cancelable job that is always active
+| `CoroutineExceptionHandler` | Handler for uncaught exception
+
+Top-level suspending functions:
+
+| **Name** | **Description**
+| ------------------- | ---------------
+| `delay` | Non-blocking sleep
+| `yield` | Yields thread in single-threaded dispatchers
+| `withContext` | Switches to a different context
+| `withTimeout` | Set execution time-limit with exception on timeout
+| `withTimeoutOrNull` | Set execution time-limit will null result on timeout
+
+Cancellation support for user-defined suspending functions is available with `suspendCancellableCoroutine`
+helper function. `NonCancellable` job object is provided to suppress cancellation with
+`run(NonCancellable) {...}` block of code.
diff --git a/core/README.md b/core/README.md
index 95ac13b..8c94c72 100644
--- a/core/README.md
+++ b/core/README.md
@@ -1,6 +1,7 @@
-# Coroutines core
+# Coroutines core for Kotlin/JVM
-This directory contains modules that provide core coroutine support.
+This directory contains modules that provide core coroutines support on Kotlin/JVM.
+Module name below corresponds to the artifact name in Maven/Gradle.
## Modules
diff --git a/core/kotlinx-coroutines-core/README.md b/core/kotlinx-coroutines-core/README.md
index 2483d4b..b9bc6ca 100644
--- a/core/kotlinx-coroutines-core/README.md
+++ b/core/kotlinx-coroutines-core/README.md
@@ -1,6 +1,6 @@
# Module kotlinx-coroutines-core
-Core primitives to work with coroutines.
+Core primitives to work with coroutines on Kotlin/JVM.
Coroutine builder functions:
diff --git a/core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt b/core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt
index ecd1b5b..cc3d005 100644
--- a/core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt
+++ b/core/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt
@@ -264,6 +264,9 @@
// ------------ low-level state-notification ------------
+ /**
+ * @suppress **Deprecated**: For binary compatibility
+ */
@Deprecated(message = "For binary compatibility", level = DeprecationLevel.HIDDEN)
public fun invokeOnCompletion(handler: CompletionHandler, onCancelling: Boolean): DisposableHandle
diff --git a/integration/README.md b/integration/README.md
index 7f5b9d8..83b0a4b 100644
--- a/integration/README.md
+++ b/integration/README.md
@@ -1,6 +1,7 @@
# Coroutines integration
-This directory contains modules that provide integration with various asynchronous callback- and future-based libraries:
+This directory contains modules that provide integration with various asynchronous callback- and future-based libraries.
+Module name below corresponds to the artifact name in Maven/Gradle.
## Modules
diff --git a/js/README.md b/js/README.md
new file mode 100644
index 0000000..4b7ea80
--- /dev/null
+++ b/js/README.md
@@ -0,0 +1,9 @@
+# Coroutines core for Kotlin/JS
+
+This directory contains modules that provide core coroutines support on Kotlin/JS.
+Module name below corresponds to the artifact name in Maven/Gradle.
+
+## Modules
+
+* [kotlinx-coroutines-core-js](kotlinx-coroutines-core-js/README.md) -- core coroutine builders and primitives.
+
diff --git a/js/kotlinx-coroutines-core-js/README.md b/js/kotlinx-coroutines-core-js/README.md
new file mode 100644
index 0000000..f295116
--- /dev/null
+++ b/js/kotlinx-coroutines-core-js/README.md
@@ -0,0 +1,74 @@
+# Module kotlinx-coroutines-core-js
+
+Core primitives to work with coroutines on Kotlin/JS.
+
+Coroutine builder functions:
+
+| **Name** | **Result** | **Scope** | **Description**
+| ------------- | ------------- | ---------------- | ---------------
+| [launch] | [Job] | [CoroutineScope] | Launches coroutine that does not have any result
+| [async] | [Deferred] | [CoroutineScope] | Returns a single value with the future result
+| [runBlocking] | `T` | [CoroutineScope] | Blocks the event loop while the coroutine runs
+
+Coroutine dispatchers implementing [CoroutineDispatcher]:
+
+| **Name** | **Description**
+| --------------------------- | ---------------
+| [DefaultDispatcher] | Posts execution to JS event loop
+| [Unconfined] | Does not confine coroutine execution in any way
+
+More context elements:
+
+| **Name** | **Description**
+| --------------------------- | ---------------
+| [NonCancellable] | A non-cancelable job that is always active
+| [CoroutineExceptionHandler] | Handler for uncaught exception
+
+Top-level suspending functions:
+
+| **Name** | **Description**
+| ------------------- | ---------------
+| [delay] | Non-blocking sleep
+| [yield] | Yields thread in single-threaded dispatchers
+| [withContext] | Switches to a different context
+| [withTimeout] | Set execution time-limit with exception on timeout
+| [withTimeoutOrNull] | Set execution time-limit will null result on timeout
+
+Cancellation support for user-defined suspending functions is available with [suspendCancellableCoroutine]
+helper function. [NonCancellable] job object is provided to suppress cancellation with
+`run(NonCancellable) {...}` block of code.
+
+# Package kotlinx.coroutines.experimental
+
+General-purpose coroutine builders, contexts, and helper functions.
+
+<!--- MODULE kotlinx-coroutines-core-js -->
+<!--- INDEX kotlinx.coroutines.experimental -->
+[launch]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/launch.html
+[Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/index.html
+[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/index.html
+[async]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/async.html
+[Deferred]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/index.html
+[runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run-blocking.html
+[CoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-dispatcher/index.html
+[DefaultDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-default-dispatcher.html
+[CommonPool]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-common-pool/index.html
+[newSingleThreadContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-single-thread-context.html
+[newFixedThreadPoolContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-fixed-thread-pool-context.html
+[java.util.concurrent.Executor.asCoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/java.util.concurrent.-executor/as-coroutine-dispatcher.html
+[Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-unconfined/index.html
+[NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/index.html
+[CoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-exception-handler/index.html
+[delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/delay.html
+[yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/yield.html
+[withContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-context.html
+[withTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-timeout.html
+[withTimeoutOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-timeout-or-null.html
+[Job.join]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/join.html
+[Job.onJoin]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/on-join.html
+[Job.isCompleted]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-job/is-completed.html
+[Deferred.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/await.html
+[Deferred.onAwait]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-deferred/on-await.html
+[suspendCancellableCoroutine]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/suspend-cancellable-coroutine.html
+[newCoroutineContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-coroutine-context.html
+<!--- END -->
diff --git a/reactive/README.md b/reactive/README.md
index c59c3a0..9b60ddb 100644
--- a/reactive/README.md
+++ b/reactive/README.md
@@ -1,6 +1,7 @@
# Coroutines for reactive streams
-This directory contains modules with utilities for various reactive stream libraries:
+This directory contains modules with utilities for various reactive stream libraries.
+Module name below corresponds to the artifact name in Maven/Gradle.
## Modules
diff --git a/ui/README.md b/ui/README.md
index 7261178..18beacb 100644
--- a/ui/README.md
+++ b/ui/README.md
@@ -1,6 +1,7 @@
# Coroutines for UI
-This directory contains modules for coroutine programming with various single-threaded UI libraries:
+This directory contains modules for coroutine programming with various single-threaded UI libraries.
+Module name below corresponds to the artifact name in Maven/Gradle.
## Modules