Better docs at top level with categorized summary of classes and functions
diff --git a/kotlinx-coroutines-core/README.md b/kotlinx-coroutines-core/README.md
index 10d20cb..5906e27 100644
--- a/kotlinx-coroutines-core/README.md
+++ b/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 @@
| [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 @@
| [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**
| ------------- | ---------------
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt
index 472cfd8..c6bfdc0 100644
--- a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt
+++ b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt
@@ -57,9 +57,10 @@
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].
*/
diff --git a/kotlinx-coroutines-jdk8/README.md b/kotlinx-coroutines-jdk8/README.md
index f1ca258..7848f59 100644
--- a/kotlinx-coroutines-jdk8/README.md
+++ b/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
-* `future { ... }` coroutine builder that returns `CompletableFuture` and works in `CommonPool` context by default.
-* `.await()` suspending function for `CompletableFuture`.
+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
+
+Additional libraries for JDK8 [CompletableFuture][java.util.concurrent.CompletableFuture].
diff --git a/kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt b/kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt
index fc80ade..b289dd8 100644
--- a/kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt
+++ b/kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt
@@ -62,7 +62,9 @@
}
/**
- * 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] .
*/