~tweak Dokka and Knit, add integration test

Author: qwwdfsad

README.md

@@ -37,6 +37,7 @@ suspend fun main() = coroutineScope {
 * [core/jvm](kotlinx-coroutines-core/jvm/) — additional core features available on Kotlin/JVM:
   * [Dispatchers.IO] dispatcher for blocking coroutines;
   * [Executor.asCoroutineDispatcher][asCoroutineDispatcher] extension, custom thread pools, and more.
+  * Integrations with [CompletableFuture] and JVM-specific extensions.
 * [core/js](kotlinx-coroutines-core/js/) — additional core features available on Kotlin/JS:
   * Integration with `Promise` via [Promise.await] and [promise] builder;
   * Integration with `Window` via [Window.asCoroutineDispatcher], etc.
@@ -56,7 +57,7 @@ suspend fun main() = coroutineScope {
 * [ui](ui/README.md) — modules that provide coroutine dispatchers for various single-threaded UI libraries:
   * Android, JavaFX, and Swing.
 * [integration](integration/README.md) — modules that provide integration with various asynchronous callback- and future-based libraries:
-  * JDK8 [CompletionStage.await], Guava [ListenableFuture.await], and Google Play Services [Task.await];
+  Guava [ListenableFuture.await], and Google Play Services [Task.await];
   * SLF4J MDC integration via [MDCContext].
 
 ## Documentation
@@ -259,9 +260,6 @@ See [Contributing Guidelines](CONTRIBUTING.md).
 
 <!--- MODULE kotlinx-coroutines-jdk8 -->
 <!--- INDEX kotlinx.coroutines.future -->
-
-[CompletionStage.await]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.future/await.html
-
 <!--- MODULE kotlinx-coroutines-guava -->
 <!--- INDEX kotlinx.coroutines.guava -->
 

build.gradle

@@ -236,7 +236,9 @@ def core_docs_url = "https://kotlinlang.org/api/kotlinx.coroutines/$coreModule/"
 def core_docs_file = "$projectDir/kotlinx-coroutines-core/build/dokka/htmlPartial/package-list"
 apply plugin: "org.jetbrains.dokka"
 
-configure(subprojects.findAll { !unpublished.contains(it.name) && it.name != coreModule }) {
+configure(subprojects.findAll { !unpublished.contains(it.name)
+        && it.name != coreModule
+        && it.name != jdk8ObsoleteModule}) {
     if (it.name != 'kotlinx-coroutines-bom') {
         apply from: rootProject.file('gradle/dokka.gradle.kts')
     }
@@ -245,7 +247,7 @@ configure(subprojects.findAll { !unpublished.contains(it.name) && it.name != cor
 
 configure(subprojects.findAll { !unpublished.contains(it.name) }) {
     if (it.name != "kotlinx-coroutines-bom") {
-        if (it.name != coreModule) {
+        if (it.name != coreModule && it.name != jdk8ObsoleteModule) {
             tasks.withType(DokkaTaskPartial.class) {
                 dokkaSourceSets.configureEach {
                     externalDocumentationLink {

buildSrc/src/main/kotlin/Projects.kt

@@ -8,6 +8,7 @@ fun Project.version(target: String): String =
     property("${target}_version") as String
 
 val coreModule = "kotlinx-coroutines-core"
+val jdk8ObsoleteModule = "kotlinx-coroutines-jdk8"
 val testModule = "kotlinx-coroutines-test"
 
 val multiplatform = setOf(coreModule, testModule)

integration-testing/src/withGuavaTest/kotlin/Jdk8InCoreIntegration.kt

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2016-2022 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package kotlinx.coroutines
+
+import kotlinx.coroutines.future.*
+import org.junit.Test
+import kotlin.test.*
+
+/*
+ * Temporary test that verifies both signatures from jdk8 and from core source-sets are used
+ */
+class Jdk8InCoreIntegration {
+
+    @Test
+    fun testFuture() = runBlocking<Unit> {
+        val future = future { yield(); 42 }
+        future.whenComplete { r, _ -> assertEquals(42, r)  }
+        assertEquals(42, future.await())
+    }
+}

integration/README.md

@@ -5,7 +5,6 @@ Module name below corresponds to the artifact name in Maven/Gradle.
 
 ## Modules
 
-* [kotlinx-coroutines-jdk8](kotlinx-coroutines-jdk8/README.md) -- integration with JDK8 `CompletableFuture` (Android API level 24).
 * [kotlinx-coroutines-guava](kotlinx-coroutines-guava/README.md) -- integration with Guava [ListenableFuture](https://github.com/google/guava/wiki/ListenableFutureExplained).
 * [kotlinx-coroutines-slf4j](kotlinx-coroutines-slf4j/README.md) -- integration with SLF4J [MDC](https://logback.qos.ch/manual/mdc.html).
 * [kotlinx-coroutines-play-services](kotlinx-coroutines-play-services) -- integration with Google Play Services [Tasks API](https://developers.google.com/android/guides/tasks).

integration/kotlinx-coroutines-jdk8/README.md

@@ -1,68 +1,3 @@
-# Module kotlinx-coroutines-jdk8
+# Stub module
 
-Integration with JDK8 [CompletableFuture] (Android API level 24).
-
-Coroutine builders:
-
-| **Name** | **Result**          | **Scope**        | **Description**
-| -------- | ------------------- | ---------------- | ---------------
-| [future] | [CompletableFuture] | [CoroutineScope] | Returns a single value with the future result 
-
-Extension functions:
-
-| **Name** | **Description**
-| -------- | ---------------
-| [CompletionStage.await][java.util.concurrent.CompletionStage.await] | Awaits for completion of the completion stage
-| [CompletionStage.asDeferred][java.util.concurrent.CompletionStage.asDeferred] | Converts completion stage to an instance of [Deferred]
-| [Deferred.asCompletableFuture][kotlinx.coroutines.Deferred.asCompletableFuture] | Converts a deferred value to the future
-
-## Example
-
-Given the following functions defined in some Java API:
-
-```java
-public CompletableFuture<Image> loadImageAsync(String name); // starts async image loading
-public Image combineImages(Image image1, Image image2); // synchronously combines two images using some algorithm
-```
-
-We can consume this API from Kotlin coroutine to load two images and combine then asynchronously. 
-The resulting function returns `CompletableFuture<Image>` for ease of use back from Java. 
-
-```kotlin
-fun combineImagesAsync(name1: String, name2: String): CompletableFuture<Image> = future {
-    val future1 = loadImageAsync(name1) // start loading first image
-    val future2 = loadImageAsync(name2) // start loading second image
-    combineImages(future1.await(), future2.await()) // wait for both, combine, and return result
-}
-```
-
-Note that this module should be used only for integration with existing Java APIs based on `CompletableFuture`. 
-Writing pure-Kotlin code that uses `CompletableFuture` is highly not recommended, since the resulting APIs based
-on the futures are quite error-prone. See the discussion on 
-[Asynchronous Programming Styles](https://github.com/Kotlin/KEEP/blob/master/proposals/coroutines.md#asynchronous-programming-styles)
-for details on general problems pertaining to any future-based API and keep in mind that `CompletableFuture` exposes
-a _blocking_ method 
-[get](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Future.html#get--) 
-that makes it especially bad choice for coroutine-based Kotlin code.
-
-# Package kotlinx.coroutines.future
-
-Integration with JDK8 [CompletableFuture] (Android API level 24).
-
-[CompletableFuture]: https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html
-
-<!--- MODULE kotlinx-coroutines-core -->
-<!--- INDEX kotlinx.coroutines -->
-
-[CoroutineScope]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html
-[Deferred]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html
-
-<!--- MODULE kotlinx-coroutines-jdk8 -->
-<!--- INDEX kotlinx.coroutines.future -->
-
-[future]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.future/future.html
-[java.util.concurrent.CompletionStage.await]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.future/await.html
-[java.util.concurrent.CompletionStage.asDeferred]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.future/as-deferred.html
-[kotlinx.coroutines.Deferred.asCompletableFuture]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-jdk8/kotlinx.coroutines.future/as-completable-future.html
-
-<!--- END -->
+Stub module for backwards compatibility. Since 1.7.0, this module was merged with core.