Dokka fixes

  * Provide module with Kotlin 1.3 API because Kotlin 1.2 from Dokka can't read classes marked as "from the future"
  * Add runConfiguration dokkaStubs which is included only during dokka task with some classpath magic for Kotlin 1.3
  * Add package.list for slf4j
  * Fix unresolved types/links in documentation
  * Suppress all internal/inherited API

Author: qwwdfsad

build.gradle

@@ -103,7 +103,7 @@ configure(subprojects.findAll { !sourceless.contains(it.name)  }) {
 
 // --------------- Configure sub-projects that are part of the library ---------------
 
-def internal = sourceless + ['benchmarks', 'knit', 'js-stub', 'binary-compatibility-validator']
+def internal = sourceless + ['benchmarks', 'knit', 'js-stub', 'stdlib-stubs', 'binary-compatibility-validator']
 
 // Reconfigure source sets to avoid long "src/main/kotlin/fqn"
 configure(subprojects.findAll { !it.name.contains(sourceless) && it.name != "benchmarks" }) {

common/kotlinx-coroutines-core-common/src/CoroutineContext.common.kt

@@ -6,6 +6,10 @@ package kotlinx.coroutines
 
 import kotlin.coroutines.*
 
+/**
+ * Creates context for the new coroutine. It installs [Dispatchers.Default] when no other dispatcher nor
+ * [ContinuationInterceptor] is specified, and adds optional support for debugging facilities (when turned on).
+ */
 public expect fun CoroutineScope.newCoroutineContext(context: CoroutineContext): CoroutineContext
 
 internal expect fun createDefaultDispatcher(): CoroutineDispatcher

common/kotlinx-coroutines-core-common/src/CoroutineDispatcher.kt

@@ -103,7 +103,7 @@ public abstract class CoroutineDispatcher :
     )
     public operator fun plus(other: CoroutineDispatcher) = other
 
-    // for nicer debugging
+    /** @suppress for nicer debugging */
     override fun toString(): String = "$classSimpleName@$hexAddress"
 }
 

common/kotlinx-coroutines-core-common/src/CoroutineScope.kt

@@ -58,7 +58,6 @@ import kotlin.coroutines.*
  * ```
  */
 public interface CoroutineScope {
-
     /**
      * Context of this scope.
      */

common/kotlinx-coroutines-core-common/src/Delay.kt

@@ -16,7 +16,7 @@ import kotlin.coroutines.*
  *
  * @suppress **This an internal API and should not be used from general code.**
  */
-@InternalCoroutinesApi // todo: Remove references from other docs
+@InternalCoroutinesApi
 public interface Delay {
     /**
      * Delays coroutine for a given time without blocking a thread and resumes it after a specified time.
@@ -65,9 +65,7 @@ public interface Delay {
  *
  * Note, that delay can be used in [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
  *
- * This function delegates to [Delay.scheduleResumeAfterDelay] if the context [CoroutineDispatcher]
- * implements [Delay] interface, otherwise it resumes using a built-in single-threaded scheduled executor service.
- *
+ * Implementation note: how exactly time is tracked is an implementation detail of [CoroutineDispatcher] in the context.
  * @param timeMillis time in milliseconds.
  */
 public suspend fun delay(timeMillis: Long) {

common/kotlinx-coroutines-core-common/src/Exceptions.common.kt

@@ -4,6 +4,9 @@
 
 package kotlinx.coroutines
 
+/**
+ * @suppress **This an internal API and should not be used from general code.**
+ */
 @InternalCoroutinesApi
 public expect class CompletionHandlerException(message: String, cause: Throwable) : RuntimeException
 

common/kotlinx-coroutines-core-common/src/NonCancellable.kt

@@ -5,12 +5,11 @@
 
 package kotlinx.coroutines
 
-import kotlinx.coroutines.NonCancellable.isActive
 import kotlinx.coroutines.selects.*
 import kotlin.coroutines.*
 
 /**
- * A non-cancelable job that is always [active][isActive]. It is designed for [withContext] function
+ * A non-cancelable job that is always [active][Job.isActive]. It is designed for [withContext] function
  * to prevent cancellation of code blocks that need to be executed without cancellation.
  *
  * Use it like this:
@@ -26,7 +25,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
      * @suppress **This an internal API and should not be used from general code.**
      */
     @InternalCoroutinesApi
-    override val isActive: Boolean  get() = true
+    override val isActive: Boolean get() = true
 
     /**
      * Always returns `false`.

common/kotlinx-coroutines-core-common/src/Runnable.common.kt

@@ -4,6 +4,7 @@
 
 package kotlinx.coroutines
 
+/** @suppress */
 public expect interface Runnable {
     public fun run()
 }

common/kotlinx-coroutines-core-common/src/Timeout.kt

@@ -20,8 +20,7 @@ import kotlin.coroutines.intrinsics.*
  * The sibling function that does not throw exception on timeout is [withTimeoutOrNull].
  * Note, that timeout action can be specified for [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
  *
- * This function delegates to [Delay.invokeOnTimeout] if the context [CoroutineDispatcher]
- * implements [Delay] interface, otherwise it tracks time using a built-in single-threaded scheduled executor service.
+ * Implementation note: how exactly time is tracked is an implementation detail of [CoroutineDispatcher] in the context.
  *
  * @param timeMillis timeout time in milliseconds.
  */
@@ -42,8 +41,7 @@ public suspend fun <T> withTimeout(timeMillis: Long, block: suspend CoroutineSco
  * The sibling function that throws exception on timeout is [withTimeout].
  * Note, that timeout action can be specified for [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
  *
- * This function delegates to [Delay.invokeOnTimeout] if the context [CoroutineDispatcher]
- * implements [Delay] interface, otherwise it tracks time using a built-in single-threaded scheduled executor service.
+ * Implementation note: how exactly time is tracked is an implementation detail of [CoroutineDispatcher] in the context.
  *
  * @param timeMillis timeout time in milliseconds.
  */

common/kotlinx-coroutines-core-common/src/channels/Channel.kt

@@ -342,7 +342,7 @@ public interface ChannelIterator<out E> {
  *   while previously sent elements **are lost**.
  *   Sender to this channel never suspends and [offer] always returns `true`.
  *
- * * When `capacity` is positive, but less than [UNLIMITED] -- it creates [ArrayChannel].
+ * * When `capacity` is positive, but less than [UNLIMITED] -- it creates array-based channel with given capacity.
  *   This channel has an array buffer of a fixed `capacity`.
  *   Sender suspends only when buffer is fully and receiver suspends only when buffer is empty.
  */

common/kotlinx-coroutines-core-common/src/internal/MainDispatcherFactory.kt

@@ -6,6 +6,7 @@ package kotlinx.coroutines.internal
 
 import kotlinx.coroutines.*
 
+/** @suppress */
 @InternalCoroutinesApi // Emulating DI for Kotlin object's
 public interface MainDispatcherFactory {
     val loadPriority: Int // higher priority wins

common/kotlinx-coroutines-core-common/src/selects/Select.kt

@@ -9,6 +9,7 @@ import kotlinx.coroutines.*
 import kotlinx.coroutines.channels.*
 import kotlinx.coroutines.internal.*
 import kotlinx.coroutines.intrinsics.*
+import kotlinx.coroutines.sync.*
 import kotlin.coroutines.*
 import kotlin.coroutines.intrinsics.*
 
@@ -150,12 +151,12 @@ public interface SelectInstance<in R> {
  *
  * | **Receiver**     | **Suspending function**                       | **Select clause**                                | **Non-suspending version**
  * | ---------------- | --------------------------------------------- | ------------------------------------------------ | --------------------------
- * | [Job]            | [join][Job.join]                              | [onJoin][SelectBuilder.onJoin]                   | [isCompleted][Job.isCompleted]
- * | [Deferred]       | [await][Deferred.await]                       | [onAwait][SelectBuilder.onAwait]                 | [isCompleted][Job.isCompleted]
- * | [SendChannel]    | [send][SendChannel.send]                      | [onSend][SelectBuilder.onSend]                   | [offer][SendChannel.offer]
- * | [ReceiveChannel] | [receive][ReceiveChannel.receive]             | [onReceive][SelectBuilder.onReceive]             | [poll][ReceiveChannel.poll]
- * | [ReceiveChannel] | [receiveOrNull][ReceiveChannel.receiveOrNull] | [onReceiveOrNull][SelectBuilder.onReceiveOrNull] | [poll][ReceiveChannel.poll]
- * | [Mutex]          | [lock][Mutex.lock]                            | [onLock][SelectBuilder.onLock]                   | [tryLock][Mutex.tryLock]
+ * | [Job]            | [join][Job.join]                              | [onJoin][Job.onJoin]                             | [isCompleted][Job.isCompleted]
+ * | [Deferred]       | [await][Deferred.await]                       | [onAwait][Deferred.onAwait]                      | [isCompleted][Job.isCompleted]
+ * | [SendChannel]    | [send][SendChannel.send]                      | [onSend][SendChannel.onSend]                     | [offer][SendChannel.offer]
+ * | [ReceiveChannel] | [receive][ReceiveChannel.receive]             | [onReceive][ReceiveChannel.onReceive]            | [poll][ReceiveChannel.poll]
+ * | [ReceiveChannel] | [receiveOrNull][ReceiveChannel.receiveOrNull] | [onReceiveOrNull][ReceiveChannel.onReceiveOrNull]| [poll][ReceiveChannel.poll]
+ * | [Mutex]          | [lock][Mutex.lock]                            | [onLock][Mutex.onLock]                           | [tryLock][Mutex.tryLock]
  * | none             | [delay]                                       | [onTimeout][SelectBuilder.onTimeout]             | none
  *
  * This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this

common/kotlinx-coroutines-core-common/test/channels/BroadcastChannelFactoryTest.kt

@@ -4,10 +4,11 @@
 
 package kotlinx.coroutines.channels
 
+import kotlinx.coroutines.*
 import kotlin.test.*
 
 
-class BroadcastChannelFactoryTest {
+class BroadcastChannelFactoryTest : TestBase() {
 
     @Test
     fun testRendezvousChannelNotSupported() {

core/kotlinx-coroutines-core/src/Runnable.kt

@@ -6,6 +6,7 @@ package kotlinx.coroutines
 
 /**
  * A runnable task for [CoroutineDispatcher.dispatch].
+ * @suppress
  */
 public actual typealias Runnable = java.lang.Runnable
 

core/kotlinx-coroutines-core/src/channels/Actor.kt

@@ -101,7 +101,7 @@ public interface ActorScope<E> : CoroutineScope, ReceiveChannel<E> {
  * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine.
  * @param capacity capacity of the channel's buffer (no buffer by default).
  * @param start coroutine start option. The default value is [CoroutineStart.DEFAULT].
- * @param onCompletion optional completion handler for the actor coroutine (see [Job.invokeOnCompletion]).
+ * @param onCompletion optional completion handler for the actor coroutine (see [Job.invokeOnCompletion])
  * @param block the coroutine code.
  */
 @ObsoleteCoroutinesApi

core/stdlib-stubs/README.md

@@ -0,0 +1 @@
+This is a workaround for Dokka to generate proper references for Kotlin 1.3 API.

core/stdlib-stubs/build.gradle

@@ -0,0 +1,9 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+compileKotlin {
+    kotlinOptions {
+        freeCompilerArgs += "-Xallow-kotlin-package"
+    }
+}

core/stdlib-stubs/src/Continuation.kt

@@ -0,0 +1,10 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package kotlin.coroutines
+
+// DOKKA STUB
+public interface Continuation<in T> {
+    public val context: CoroutineContext
+    public fun resumeWith(result: Result<T>)
+}

core/stdlib-stubs/src/ContinuationInterceptor.kt

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package kotlin.coroutines
+
+// DOKKA STUB
+public interface ContinuationInterceptor : CoroutineContext.Element {
+    companion object Key : CoroutineContext.Key<ContinuationInterceptor>
+    public fun <T> interceptContinuation(continuation: Continuation<T>): Continuation<T>
+    public fun releaseInterceptedContinuation(continuation: Continuation<*>): Continuation<*> {
+        return continuation
+    }
+    public override operator fun <E : CoroutineContext.Element> get(key: CoroutineContext.Key<E>): E? = TODO()
+    public override fun minusKey(key: CoroutineContext.Key<*>): CoroutineContext = TODO()
+}

core/stdlib-stubs/src/CoroutineContext.kt

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package kotlin.coroutines
+
+// DOKKA STUB
+public interface CoroutineContext {
+    public operator fun <E : Element> get(key: Key<E>): E?
+    public fun <R> fold(initial: R, operation: (R, Element) -> R): R
+    public operator fun plus(context: CoroutineContext): CoroutineContext = TODO()
+    public fun minusKey(key: Key<*>): CoroutineContext
+    public interface Key<E : Element>
+    public interface Element : CoroutineContext {
+        public val key: Key<*>
+
+        public override operator fun <E : Element> get(key: Key<E>): E? =
+            @Suppress("UNCHECKED_CAST")
+            if (this.key == key) this as E else null
+
+        public override fun <R> fold(initial: R, operation: (R, Element) -> R): R =
+            operation(initial, this)
+
+        public override fun minusKey(key: Key<*>): CoroutineContext =
+            if (this.key == key) EmptyCoroutineContext else this
+    }
+}
+
+public object EmptyCoroutineContext : CoroutineContext {
+    private const val serialVersionUID: Long = 0
+    private fun readResolve(): Any = EmptyCoroutineContext
+
+    public override fun <E : CoroutineContext.Element> get(key: CoroutineContext.Key<E>): E? = null
+    public override fun <R> fold(initial: R, operation: (R, CoroutineContext.Element) -> R): R = initial
+    public override fun plus(context: CoroutineContext): CoroutineContext = context
+    public override fun minusKey(key: CoroutineContext.Key<*>): CoroutineContext = this
+    public override fun hashCode(): Int = 0
+    public override fun toString(): String = "EmptyCoroutineContext"
+}

core/stdlib-stubs/src/Result.kt

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlin
+
+interface Result<out T> {
+    public val value: T
+    public val isSuccess: Boolean
+    public val isFailure: Boolean
+    public fun exceptionOrNull(): Throwable?
+    public fun getOrNull(): T?
+    public fun getOrThrow(): T
+}

docs/channels.md

@@ -627,6 +627,7 @@ delay between elements.
 <!--- INDEX kotlinx.coroutines -->
 [CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html
 [runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html
+[kotlin.coroutines.CoroutineContext.cancelChildren]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/kotlin.coroutines.-coroutine-context/cancel-children.html
 [Dispatchers.Default]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-default.html
 <!--- INDEX kotlinx.coroutines.channels -->
 [Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-channel/index.html

gradle/dokka.gradle

@@ -16,6 +16,10 @@ def makeLinkMapping(dokka, projectDir) {
     }
 }
 
+configurations {
+    dokkaStubs.extendsFrom compileOnly
+}
+
 if (platform == "jvm") {
     apply plugin: 'org.jetbrains.dokka'
 
@@ -24,14 +28,24 @@ if (platform == "jvm") {
         includes = ['README.md']
     }
 
+    dependencies {
+        dokkaStubs project(":stdlib-stubs")
+    }
+
     dokka {
+        kotlinTasks { [] }
         outputFormat = 'kotlin-website'
+        afterEvaluate {
+            dependsOn(project.configurations.dokkaStubs)
+            dependsOn(project.configurations.compileClasspath)
+            classpath = project.configurations.dokkaStubs.files + project.configurations.compileClasspath.files + project.sourceSets.main.output.files
+        }
     }
 
     if (project.name == coroutines_core) {
         // Custom configuration for MPP modules
         dependencies {
-            compileOnly project(":js-stub") // so that JS library reference can resolve properly
+            dokkaStubs project(":js-stub") // so that JS library reference can resolve properly
         }
 
         dokka {
@@ -63,8 +77,9 @@ if (platform == "jvm") {
                 dependsOn(tasks.getByPath(":$project.name:classes"))
                 dependsOn(tasks.getByPath(":$project.name-js:classes"))
                 dependsOn(tasks.getByPath(":$project.name-common:classes"))
+                dependsOn(project.configurations.dokkaStubs)
                 dependsOn(project.configurations.compileClasspath)
-                classpath = project.configurations.compileClasspath.files + project.sourceSets.main.output.files
+                classpath = project.configurations.dokkaStubs.files + project.configurations.compileClasspath.files + project.sourceSets.main.output.files
             }
         }
     }

integration/kotlinx-coroutines-play-services/build.gradle

@@ -38,10 +38,12 @@ dependencies {
 tasks.withType(dokka.getClass()) {
     externalDocumentationLink {
         url = new URL("https://developers.google.com/android/reference/")
-        /*
-         * This is workaround for missing package list in Google API
-         */
-        packageListUrl = rootDir.toPath().resolve("integration/kotlinx-coroutines-play-services/resources/package.list").toUri().toURL()
+        // This is workaround for missing package list in Google API
+        packageListUrl = projectDir.toPath().resolve("package.list").toUri().toURL()
+    }
+
+    afterEvaluate {
+        classpath += project.configurations.aar.files
     }
 }
 

integration/kotlinx-coroutines-play-services/resources/package.list renamed to integration/kotlinx-coroutines-play-services/package.list

@@ -5,8 +5,9 @@ dependencies {
     testRuntime 'ch.qos.logback:logback-core:1.2.3'
 }
 
-//tasks.withType(dokka.getClass()) {
-//    externalDocumentationLink {
-//        url = new URL("https://www.slf4j.org/apidocs/")
-//    }
-//}
+tasks.withType(dokka.getClass()) {
+    externalDocumentationLink {
+        packageListUrl = projectDir.toPath().resolve("package.list").toUri().toURL()
+        url = new URL("https://www.slf4j.org/apidocs/")
+    }
+}

integration/kotlinx-coroutines-slf4j/build.gradle

@@ -0,0 +1,21 @@
+org.apache.commons.logging
+org.apache.commons.logging.impl
+org.apache.log4j
+org.apache.log4j.helpers
+org.apache.log4j.spi
+org.apache.log4j.xml
+org.slf4j
+org.slf4j.agent
+org.slf4j.bridge
+org.slf4j.cal10n
+org.slf4j.event
+org.slf4j.ext
+org.slf4j.helpers
+org.slf4j.instrumentation
+org.slf4j.jul
+org.slf4j.log4j12
+org.slf4j.nop
+org.slf4j.osgi.logservice.impl
+org.slf4j.profiler
+org.slf4j.simple
+org.slf4j.spi