MPP: Job.getCancellationException docs & proper Throwable.cause override

Author: elizarov

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

@@ -87,17 +87,18 @@ public actual interface Job : CoroutineContext.Element {
     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 @@ public actual interface DisposableHandle {
  * 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 open class CancellationException actual constructor(message: Strin
  */
 public actual class JobCancellationException public actual constructor(
     message: String,
-    cause: Throwable?,
+    public override val cause: Throwable?,
     /**
      * The job that was cancelled.
      */