Better docs at top level with categorized summary of classes and functions

Author: elizarov

kotlinx-coroutines-core/README.md

@@ -2,7 +2,7 @@
 
 Core primitives to work with coroutines.
 
-This module provides the following coroutine builders:
+Coroutine builder functions:
 
 | **Name**      | **Result**    | **Scope**        | **Description**
 | ------------- | ------------- | ---------------- | ---------------
@@ -11,7 +11,7 @@ This module provides the following coroutine builders:
 | [produce]     | [ProducerJob] | [ProducerScope]  | Produces a stream of elements
 | [runBlocking] | `T`           | [CoroutineScope] | Blocks the thread while the coroutine runs
 
-These builders can be used with the following [coroutine dispatchers][CoroutineDispatcher]:
+Coroutine dispatchers implementing [CoroutineDispatcher]:
 
 | **Name**                    | **Description**
 | --------------------------- | ---------------
@@ -28,7 +28,7 @@ Synchronization primitives for coroutines:
 | [Mutex]    | [lock][Mutex.lock]                                          | Mutual exclusion 
 | [Channel]  | [send][SendChannel.send], [receive][ReceiveChannel.receive] | Communication channel (aka queue or exchanger)
 
-The following _top-level_ suspending functions are provided to be used inside coroutines:
+Top-level suspending functions:
 
 | **Name**      | **Description**
 | ------------- | ---------------

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt

@@ -57,9 +57,10 @@ public interface Deferred<out T> : Job {
     val isCancelled: Boolean
 
     /**
-     * Awaits for completion of this value without blocking a thread and resumes when deferred computation is complete.
-     * This suspending function is cancellable.
+     * Awaits for completion of this value without blocking a thread and resumes when deferred computation is complete,
+     * returning the resulting value or throwing the corresponding exception if the deferred had completed exceptionally.
      *
+     * This suspending function is cancellable.
      * If the [Job] of the current coroutine is completed while this suspending function is waiting, this function
      * immediately resumes with [CancellationException].
      */

kotlinx-coroutines-jdk8/README.md

@@ -2,9 +2,32 @@
 
 Additional libraries for JDK8 (or Android API level 24).
 
-# Package kotlinx.coroutines.experimental.jdk8
+Coroutine builders:
 
-Additional libraries for JDK8 (or Android API level 24).
+| **Name** | **Result** | **Scope**  | **Description**
+| -------- | ---------- | ---------- | ---------------
+| [future] | [CompletableFuture][java.util.concurrent.CompletableFuture] | [CoroutineScope] | Returns a single value with the future result 
+
+Extension functions:
+
+| **Name** | **Description**
+| -------- | ---------------
+| [CompletableFuture.await][java.util.concurrent.CompletableFuture.await] | Awaits for completion of the future
+| [Deferred.toCompletableFuture][kotlinx.coroutines.experimental.Deferred.toCompletableFuture] | Converts a deferred value to the future
+
+<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core -->
+<!--- DOCS_ROOT kotlinx-coroutines-core/target/dokka/kotlinx-coroutines-core -->
+<!--- INDEX kotlinx.coroutines.experimental -->
+[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-coroutine-scope/index.html
+<!--- SITE_ROOT https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8 -->
+<!--- DOCS_ROOT kotlinx-coroutines-jdk8/target/dokka/kotlinx-coroutines-jdk8 -->
+<!--- INDEX kotlinx.coroutines.experimental.future -->
+[java.util.concurrent.CompletableFuture]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.experimental.future/java.util.concurrent.-completable-future/index.html
+[java.util.concurrent.CompletableFuture.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.experimental.future/java.util.concurrent.-completable-future/await.html
+[kotlinx.coroutines.experimental.Deferred.toCompletableFuture]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.experimental.future/kotlinx.coroutines.experimental.-deferred/to-completable-future.html
+[future]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.experimental.future/future.html
+<!--- END -->
+
+# Package kotlinx.coroutines.experimental.future
 
-* `future { ... }` coroutine builder that returns `CompletableFuture` and works in `CommonPool` context by default.
-* `.await()` suspending function for `CompletableFuture`.
+Additional libraries for JDK8 [CompletableFuture][java.util.concurrent.CompletableFuture].

kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt

@@ -62,7 +62,9 @@ public fun <T> Deferred<T>.toCompletableFuture(): CompletableFuture<T> {
 }
 
 /**
- * Awaits for completion of the future without blocking a thread. This suspending function is cancellable.
+ * Awaits for completion of the future without blocking a thread.
+ *
+ * This suspending function is cancellable.
  * If the [Job] of the current coroutine is completed while this suspending function is waiting, this function
  * immediately resumes with [CancellationException] .
  */