MPP: Job.getCancellationException docs & proper Throwable.cause override
diff --git a/js/kotlinx-coroutines-core-js/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt b/js/kotlinx-coroutines-core-js/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt
index b04b2d9..c9fe6ca 100644
--- a/js/kotlinx-coroutines-core-js/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt
+++ b/js/kotlinx-coroutines-core-js/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt
@@ -87,17 +87,18 @@
public actual val isCancelled: Boolean
/**
- * Returns [CancellationException] that signals the completion of this job.
+ * Returns [CancellationException] that signals the completion of this job. This function is
+ * used by [cancellable][suspendCancellableCoroutine] suspending functions. They throw exception
+ * returned by this function when they suspend in the context of this job and this job becomes _complete_.
*
- * It returns the original [cancel] cause if it is an instance of [CancellationException] or
- * an instance of [JobCancellationException] if this job was cancelled with a cause of
- * different type, was cancelled without a cause or had completed normally.
+ * This function returns the original [cancel] cause of this job if that `cause` was an instance of
+ * [CancellationException]. Otherwise (if this job was cancelled with a cause of a different type, or
+ * was cancelled without a cause, or had completed normally), an instance of [JobCancellationException] is
+ * returned. The [JobCancellationException.cause] of the resulting [JobCancellationException] references
+ * the original cancellation cause that was passed to [cancel] function.
*
- * This function throws [IllegalStateException] when invoked for an job that has not
+ * This function throws [IllegalStateException] when invoked on a job that has not
* [completed][isCompleted] nor [cancelled][isCancelled] yet.
- *
- * The [cancellable][suspendCancellableCoroutine] suspending functions throw this exception
- * when trying to suspend in the context of this job.
*/
public actual fun getCancellationException(): CancellationException
@@ -255,7 +256,8 @@
* This exception gets thrown if an exception is caught while processing [CompletionHandler] invocation for [Job].
*/
public actual class CompletionHandlerException public actual constructor(
- message: String, cause: Throwable
+ message: String,
+ public override val cause: Throwable
) : RuntimeException(message.withCause(cause))
public actual open class CancellationException actual constructor(message: String) : IllegalStateException(message)
@@ -267,7 +269,7 @@
*/
public actual class JobCancellationException public actual constructor(
message: String,
- cause: Throwable?,
+ public override val cause: Throwable?,
/**
* The job that was cancelled.
*/