MPP: Common CoroutineContext extensions & doc suppress

Author: elizarov

common/kotlinx-coroutines-core-common/src/main/kotlin/kotlinx/coroutines/experimental/CommonJob.kt

@@ -57,6 +57,11 @@ public expect class JobCancellationException(
     val job: Job
 }
 
+@Suppress("EXPECTED_DECLARATION_WITH_DEFAULT_PARAMETER")
+public expect fun CoroutineContext.cancel(cause: Throwable? = null): Boolean
+@Suppress("EXPECTED_DECLARATION_WITH_DEFAULT_PARAMETER")
+public expect fun CoroutineContext.cancelChildren(cause: Throwable? = null)
+
 public expect fun Job.disposeOnCompletion(handle: DisposableHandle): DisposableHandle
 public expect suspend fun Job.cancelAndJoin()
 @Suppress("EXPECTED_DECLARATION_WITH_DEFAULT_PARAMETER", "EXTENSION_SHADOWED_BY_MEMBER") // See KT-21598

core/kotlinx-coroutines-core/README.md

@@ -1,6 +1,6 @@
 # Module kotlinx-coroutines-core
 
-Core primitives to work with coroutines on Kotlin/JVM.
+Core primitives to work with coroutines.
 
 Coroutine builder functions:
 

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

@@ -111,6 +111,7 @@ public suspend fun delay(time: Long, unit: TimeUnit = TimeUnit.MILLISECONDS) {
 
 /**
  * An implementation of [DisposableHandle] that cancels the specified future on dispose.
+ * @suppress **This is unstable API and it is subject to change.**
  */
 public class DisposableFutureHandle(private val future: Future<*>) : DisposableHandle {
     override fun dispose() {

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

@@ -509,15 +509,15 @@ public actual suspend fun Job.joinChildren() {
  * cancelled as a result of this invocation and `false` if there is no job in the context or if it was already
  * cancelled or completed. See [Job.cancel] for details.
  */
-public fun CoroutineContext.cancel(cause: Throwable? = null): Boolean =
+public actual fun CoroutineContext.cancel(cause: Throwable? = null): Boolean =
     this[Job]?.cancel(cause) ?: false
 
 /**
  * Cancels all children of the [Job] in this context with an optional cancellation [cause].
  * It does not do anything if there is no job in the context or it has no children.
  * See [Job.cancelChildren] for details.
  */
-public fun CoroutineContext.cancelChildren(cause: Throwable? = null) {
+public actual fun CoroutineContext.cancelChildren(cause: Throwable? = null) {
    this[Job]?.cancelChildren(cause)
 }
 
@@ -530,6 +530,7 @@ public suspend fun Job.join() = this.join()
 
 /**
  * No-op implementation of [Job.Registration].
+ * @suppress: **Deprecated**: Replace with [NonDisposableHandle]
  */
 @Deprecated(message = "Replace with `NonDisposableHandle`",
     replaceWith = ReplaceWith("NonDisposableHandle"))
@@ -1170,7 +1171,7 @@ public open class JobSupport(active: Boolean) : Job, SelectClause0, SelectClause
     protected open fun afterCompletion(state: Any?, mode: Int) {}
 
     // for nicer debugging
-    override final fun toString(): String =
+    final override fun toString(): String =
         "${nameString()}{${stateString()}}@$hexAddress"
 
     /**
@@ -1400,7 +1401,7 @@ internal abstract class JobNode<out J : Job>(
     final override val isActive: Boolean get() = true
     final override val list: JobSupport.NodeList? get() = null
     final override fun dispose() = (job as JobSupport).removeNode(this)
-    override abstract fun invoke(reason: Throwable?)
+    abstract override fun invoke(reason: Throwable?)
 }
 
 private class InvokeOnCompletion(

js/kotlinx-coroutines-core-js/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt

@@ -306,6 +306,25 @@ private fun IllegalStateException(message: String, cause: Throwable?) =
 private fun String.withCause(cause: Throwable?) =
     if (cause == null) this else "$this; caused by $cause"
 
+// -------------------- CoroutineContext extensions --------------------
+
+/**
+ * Cancels [Job] of this context with an optional cancellation [cause]. The result is `true` if the job was
+ * cancelled as a result of this invocation and `false` if there is no job in the context or if it was already
+ * cancelled or completed. See [Job.cancel] for details.
+ */
+public actual fun CoroutineContext.cancel(cause: Throwable? = null): Boolean =
+    this[Job]?.cancel(cause) ?: false
+
+/**
+ * Cancels all children of the [Job] in this context with an optional cancellation [cause].
+ * It does not do anything if there is no job in the context or it has no children.
+ * See [Job.cancelChildren] for details.
+ */
+public actual fun CoroutineContext.cancelChildren(cause: Throwable? = null) {
+    this[Job]?.cancelChildren(cause)
+}
+
 // -------------------- Job extensions --------------------
 
 /**

js/kotlinx-coroutines-core-js/src/main/kotlin/kotlinx/coroutines/experimental/internal/LinkedList.kt

@@ -18,6 +18,9 @@ package kotlinx.coroutines.experimental.internal
 
 private typealias Node = LinkedListNode
 
+/**
+ * @suppress **This is unstable API and it is subject to change.**
+ */
 public open class LinkedListNode {
     public var next = this
         private set
@@ -46,6 +49,9 @@ public open class LinkedListNode {
     }
 }
 
+/**
+ * @suppress **This is unstable API and it is subject to change.**
+ */
 public open class LinkedListHead : LinkedListNode() {
     public val isEmpty get() = next === this