Per-module readme files

Author: elizarov

README.md

@@ -4,23 +4,14 @@ Library support for Kotlin coroutines. This is a companion version for Kotlin 1.
 
 ## Modules and features
 
-* `kotlinx-coroutines-core` module with core primitives to work with coroutines. 
+* [kotlinx-coroutines-core](kotlinx-coroutines-core) module with core primitives to work with coroutines. 
    Its functionality is covered by the [guide to kotlinx.coroutines](coroutines-guide.md). 
+* [kotlinx-coroutines-jdk8](kotlinx-coroutines-jdk8) module with additional libraries for JDK8 (or Android API level 24).
+* [kotlinx-coroutines-nio](kotlinx-coroutines-nio) module with extensions for asynchronous IO on JDK7+.
+* [kotlinx-coroutines-swing](kotlinx-coroutines-swing) module with `Swing` context for Swing UI applications.
+* [kotlinx-coroutines-javafx](kotlinx-coroutines-javafx) module with `JavaFx` context for JavaFX UI applications.
+* [kotlinx-coroutines-rx](kotlinx-coroutines-rx) module with utilities for [RxJava](https://github.com/ReactiveX/RxJava).
 
-* `kotlinx-coroutines-jdk8` module with additional libraries for JDK8 (or Android API level 24).
-  * `future { ... }` coroutine builder that returns `CompletableFuture` and works in `CommonPool` context by default.
-  * `.await()` suspending function for `CompletableFuture`.
-
-* `kotlinx-coroutines-nio` module with extensions for asynchronous IO on JDK7+.
-
-* `kotlinx-coroutines-swing` module with `Swing` context for Swing UI applications.
-
-* `kotlinx-coroutines-javafx` module with `JavaFx` context for JavaFX UI applications.
-
-* `kotlinx-coroutines-rx` module with utilities to build `Observable` objects from
-[RxJava](https://github.com/ReactiveX/RxJava) with imperative coroutines and consume their values 
-from inside coroutines. It is in very basic form now (example-only, not even close to production use)
-
 ## References and documentation
 
 * [Guide to kotlinx.coroutines by example](coroutines-guide.md) 

kotlinx-coroutines-core/README.md

@@ -0,0 +1,32 @@
+# Module kotlinx-coroutines-core
+
+Core primitives to work with coroutines.
+ 
+# Package kotlinx.coroutines.experimental
+
+General-purpose coroutine builders and contexts.
+
+* `launch(context) {...}` to start a coroutine in the given context and get reference to its `Job`.
+* `run(context) {...}` to switch to a different context inside a coroutine.
+* `runBlocking {...}` to use asynchronous Kotlin APIs from a thread-blocking code.  
+* `defer(context) {...}` and `lazyDefer(context) {...}` to get a deferred result of coroutine execution in a 
+   non-blocking way via a light-weight future interface called `Deferred`.
+* `delay(...)` for a non-blocking sleep in coroutines and 
+  `yield()` to release a thread in single-threaded dispatchers.
+* `withTimeout(timeout) {...}` scope function to easily set coroutine time-limit (deadline),
+   and `NonCancellable` context to avoid it when needed.
+* `CommonPool` and `Unconfined` contexts, access to `context` of a parent coroutine in its `CoroutineScope`.
+* `newSingleThreadContext(...)` and `newFixedThreadPoolContext(...)` functions, 
+  `Executor.toCoroutineDispatcher()` extension.
+* Cancellation support with `Job` interface and `suspendCancellableCoroutine` helper function.
+* Debugging facilities for coroutines (run JVM with `-ea` or `-Dkotlinx.coroutines.debug` options) and
+  `newCoroutineContext(context)` function to write user-defined coroutine builders that work with these
+   debugging facilities.
+
+# Package kotlinx.coroutines.experimental.channels
+
+Channels -- non-blocking primitives for communicating a stream of values between coroutines.
+
+* `Channel`, `SendChannel`, and `ReceiveChannel` interfaces,
+* `RendezvousChannel` (unbuffered) and `ArrayChannel` (buffered) implementations
+* `Channel()` factory function and `buildChannel{}` coroutines builder.

kotlinx-coroutines-javafx/README.md

@@ -0,0 +1,7 @@
+# Module kotlinx-coroutines-javafx
+
+Provides `JavaFx` context for JavaFX UI applications.
+
+# Package kotlinx.coroutines.experimental.javafx
+
+Provides `JavaFx` context for JavaFX UI applications.

kotlinx-coroutines-jdk8/README.md

@@ -0,0 +1,10 @@
+# Module kotlinx-coroutines-jdk8
+
+Additional libraries for JDK8 (or Android API level 24).
+
+# Package kotlinx.coroutines.experimental.jdk8
+
+Additional libraries for JDK8 (or Android API level 24).
+
+* `future { ... }` coroutine builder that returns `CompletableFuture` and works in `CommonPool` context by default.
+* `.await()` suspending function for `CompletableFuture`.

kotlinx-coroutines-nio/README.md

@@ -0,0 +1,11 @@
+# Module kotlinx-coroutines-nio
+
+Extensions for asynchronous IO on JDK7+.
+
+# Package kotlinx.coroutines.experimental.nio
+
+Extensions for asynchronous IO on JDK7+.
+
+* `AsynchronousFileChannel` extensions `aLock`, `aRead`, and `aWrite`.
+* `AsynchronousServerSocketChannel` extension `aAccept`.
+* `AsynchronousSocketChannel` extensions `aConnect`, `aRead`, and `aWrite`.

kotlinx-coroutines-rx/README.md

@@ -0,0 +1,8 @@
+# Module kotlinx-coroutines-rx
+
+Utilities for [RxJava](https://github.com/ReactiveX/RxJava).
+It is in very basic form now (example-only, not even close to production use).
+
+# Package kotlinx.coroutines.experimental.rx
+
+Utilities for [RxJava](https://github.com/ReactiveX/RxJava).

kotlinx-coroutines-swing/README.md

@@ -0,0 +1,7 @@
+# Module kotlinx-coroutines-swing
+
+Provides `Swing` context for Swing UI applications.
+
+# Package kotlinx.coroutines.experimental.swing
+
+Provides `Swing` context for Swing UI applications.