Clarify docs for CancellableContinuation (Kotlin#800)

qwwdfsad · web-flow · commit 49b630536981 · 2018-11-06T15:38:56.000+03:00
Clarify docs for CancellableContinuation Fixes Kotlin#712
diff --git a/common/kotlinx-coroutines-core-common/src/CancellableContinuation.kt b/common/kotlinx-coroutines-core-common/src/CancellableContinuation.kt
@@ -29,8 +29,10 @@ import kotlin.jvm.*
  *
  * A [cancelled][isCancelled] continuation implies that it is [completed][isCompleted].
  *
- * Invocation of [resume] or [resumeWithException] in _resumed_ state produces [IllegalStateException]
- * but is ignored in _cancelled_ state.
+ * Invocation of [resume] or [resumeWithException] in _resumed_ state produces [IllegalStateException].
+ * Invocation of [resume] in _cancelled_ state is ignored (it is a trivial race between resume from the continuation owner and
+ * outer job cancellation and cancellation wins).
+ * Invocation of [resumeWithException] in _cancelled_ state triggers exception handling of passed exception.
  *
  * ```
  *    +-----------+   resume    +---------+

Original file line number	Diff line number	Diff line change
`@@ -29,8 +29,10 @@ import kotlin.jvm.*`
`29`	`29`	`*`
`30`	`30`	`* A [cancelled][isCancelled] continuation implies that it is [completed][isCompleted].`
`31`	`31`	`*`
`32`		`- * Invocation of [resume] or [resumeWithException] in _resumed_ state produces [IllegalStateException]`
`33`		`- * but is ignored in _cancelled_ state.`
	`32`	`+ * Invocation of [resume] or [resumeWithException] in _resumed_ state produces [IllegalStateException].`
	`33`	`+ * Invocation of [resume] in _cancelled_ state is ignored (it is a trivial race between resume from the continuation owner and`
	`34`	`+ * outer job cancellation and cancellation wins).`
	`35`	`+ * Invocation of [resumeWithException] in _cancelled_ state triggers exception handling of passed exception.`
`34`	`36`	`*`
`35`	`37`	* ```
`36`	`38`	`* +-----------+ resume +---------+`