Added clarification on deprecation version in code, better CE messages

elizarov · elizarov · commit 73b456b998ef · 2019-03-06T17:18:27.000+03:00
diff --git a/integration/kotlinx-coroutines-jdk8/src/future/Future.kt b/integration/kotlinx-coroutines-jdk8/src/future/Future.kt
@@ -73,7 +73,7 @@ public fun <T> Deferred<T>.asCompletableFuture(): CompletableFuture<T> {
     val future = CompletableFuture<T>()
     future.whenComplete { _, exception ->
         cancel(exception?.let {
-            it as? CancellationException ?: CancellationException("Future failed", it)
+            it as? CancellationException ?: CancellationException("CompletableFuture was completed exceptionally", it)
         })
     }
     invokeOnCompletion {
diff --git a/kotlinx-coroutines-core/common/src/Job.kt b/kotlinx-coroutines-core/common/src/Job.kt
@@ -166,13 +166,13 @@ public interface Job : CoroutineContext.Element {
     /**
      * @suppress This method implements old version of JVM ABI. Use [cancel].
      */
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
     public fun cancel() = cancel(null)
 
     /**
      * @suppress This method has bad semantics when cause is not a [CancellationException]. Use [cancel].
      */
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
     public fun cancel(cause: Throwable? = null): Boolean
 
     // ------------ parent-child ------------
@@ -358,7 +358,7 @@ public fun Job(parent: Job? = null): CompletableJob = JobImpl(parent)
 
 /** @suppress Binary compatibility only */
 @Suppress("FunctionName")
-@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
 @JvmName("Job")
 public fun Job0(parent: Job? = null): Job = Job(parent)
 
@@ -488,13 +488,13 @@ public fun Job.cancelChildren(cause: CancellationException? = null) {
 /**
  * @suppress This method implements old version of JVM ABI. Use [cancel].
  */
-@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
 public fun Job.cancelChildren() = cancelChildren(null)
 
 /**
  * @suppress This method has bad semantics when cause is not a [CancellationException]. Use [Job.cancelChildren].
  */
-@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
 public fun Job.cancelChildren(cause: Throwable? = null) {
     children.forEach { (it as? JobSupport)?.cancelInternal(cause) }
 }
@@ -531,13 +531,13 @@ public fun CoroutineContext.cancel(cause: CancellationException? = null) {
 /**
  * @suppress This method implements old version of JVM ABI. Use [CoroutineContext.cancel].
  */
-@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
 public fun CoroutineContext.cancel() = cancel(null)
 
 /**
  * @suppress This method has bad semantics when cause is not a [CancellationException]. Use [CoroutineContext.cancel].
  */
-@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
 public fun CoroutineContext.cancel(cause: Throwable? = null): Boolean =
     @Suppress("DEPRECATION")
     (this[Job] as? JobSupport)?.cancelInternal(cause) ?: false
@@ -554,13 +554,13 @@ public fun CoroutineContext.cancelChildren(cause: CancellationException? = null)
 /**
  * @suppress This method implements old version of JVM ABI. Use [CoroutineContext.cancelChildren].
  */
-@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
 public fun CoroutineContext.cancelChildren() = cancelChildren(null)
 
 /**
  * @suppress This method has bad semantics when cause is not a [CancellationException]. Use [CoroutineContext.cancelChildren].
  */
-@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
 public fun CoroutineContext.cancelChildren(cause: Throwable? = null) {
     this[Job]?.children?.forEach { (it as? JobSupport)?.cancelInternal(cause) }
 }
diff --git a/kotlinx-coroutines-core/common/src/JobSupport.kt b/kotlinx-coroutines-core/common/src/JobSupport.kt
@@ -573,12 +573,12 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
 
     // HIDDEN in Job interface. Invoked only by legacy compiled code.
     // external cancel with (optional) cause, never invoked implicitly from internal machinery
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Added since 1.2.0 for binary compatibility with versions <= 1.1.x")
     public override fun cancel(cause: Throwable?): Boolean =
         cancelInternal(cause)
 
     // It is overridden in channel-linked implementation
-    // Note: Boolean result is used only in DEPRECATED functions
+    // Note: Boolean result is used only in HIDDEN DEPRECATED functions that were public in versions <= 1.1.x
     public open fun cancelInternal(cause: Throwable?): Boolean =
         cancelImpl(cause) && handlesException
 
diff --git a/kotlinx-coroutines-core/common/src/NonCancellable.kt b/kotlinx-coroutines-core/common/src/NonCancellable.kt
@@ -98,7 +98,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
      * Always returns `false`.
      * @suppress This method has bad semantics when cause is not a [CancellationException]. Use [cancel].
      */
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
     override fun cancel(cause: Throwable?): Boolean = false // never handles exceptions
 
     /**
diff --git a/kotlinx-coroutines-core/common/src/Supervisor.kt b/kotlinx-coroutines-core/common/src/Supervisor.kt
@@ -33,7 +33,7 @@ public fun SupervisorJob(parent: Job? = null) : CompletableJob = SupervisorJobIm
 
 /** @suppress Binary compatibility only */
 @Suppress("FunctionName")
-@Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility")
+@Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
 @JvmName("SupervisorJob")
 public fun SupervisorJob0(parent: Job? = null) : Job = SupervisorJob(parent)
 
diff --git a/kotlinx-coroutines-core/common/src/channels/AbstractChannel.kt b/kotlinx-coroutines-core/common/src/channels/AbstractChannel.kt
@@ -655,7 +655,7 @@ internal abstract class AbstractChannel<E> : AbstractSendChannel<E>(), Channel<E
         return if (result === POLL_FAILED) null else receiveOrNullResult(result)
     }
 
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
     final override fun cancel(cause: Throwable?): Boolean =
         cancelInternal(cause)
 
diff --git a/kotlinx-coroutines-core/common/src/channels/ArrayBroadcastChannel.kt b/kotlinx-coroutines-core/common/src/channels/ArrayBroadcastChannel.kt
@@ -67,7 +67,7 @@ internal class ArrayBroadcastChannel<E>(
         return true
     }
 
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
     override fun cancel(cause: Throwable?): Boolean =
         cancelInternal(cause)
 
diff --git a/kotlinx-coroutines-core/common/src/channels/Broadcast.kt b/kotlinx-coroutines-core/common/src/channels/Broadcast.kt
@@ -95,7 +95,7 @@ private open class BroadcastCoroutine<E>(
     override val channel: SendChannel<E>
         get() = this
 
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
     final override fun cancel(cause: Throwable?): Boolean =
         cancelInternal(cause)
 
diff --git a/kotlinx-coroutines-core/common/src/channels/Channel.kt b/kotlinx-coroutines-core/common/src/channels/Channel.kt
@@ -257,13 +257,13 @@ public interface ReceiveChannel<out E> {
     /**
      * @suppress This method implements old version of JVM ABI. Use [cancel].
      */
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
     public fun cancel() = cancel(null)
 
     /**
      * @suppress This method has bad semantics when cause is not a [CancellationException]. Use [cancel].
      */
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
     public fun cancel(cause: Throwable? = null): Boolean
 }
 
diff --git a/kotlinx-coroutines-core/common/src/channels/ChannelCoroutine.kt b/kotlinx-coroutines-core/common/src/channels/ChannelCoroutine.kt
@@ -19,7 +19,7 @@ internal open class ChannelCoroutine<E>(
         cancelInternal(null)
     }
 
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
     final override fun cancel(cause: Throwable?): Boolean =
         cancelInternal(cause)
 
diff --git a/kotlinx-coroutines-core/common/src/channels/Channels.common.kt b/kotlinx-coroutines-core/common/src/channels/Channels.common.kt
@@ -67,7 +67,7 @@ public fun ReceiveChannel<*>.consumes(): CompletionHandler = { cause: Throwable?
 @PublishedApi
 internal fun ReceiveChannel<*>.cancelConsumed(cause: Throwable?) {
     cancel(cause?.let {
-        it as? CancellationException ?: CancellationException("Consumed", it)
+        it as? CancellationException ?: CancellationException("Channel was consumed, consumer had failed", it)
     })
 }
 
diff --git a/kotlinx-coroutines-core/common/src/channels/ConflatedBroadcastChannel.kt b/kotlinx-coroutines-core/common/src/channels/ConflatedBroadcastChannel.kt
@@ -204,7 +204,7 @@ public class ConflatedBroadcastChannel<E>() : BroadcastChannel<E> {
     /**
      * @suppress This method has bad semantics when cause is not a [CancellationException]. Use [cancel].
      */
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
     public override fun cancel(cause: Throwable?): Boolean = close(cause)
 
     /**
diff --git a/kotlinx-coroutines-core/common/test/channels/TestChannelKind.kt b/kotlinx-coroutines-core/common/test/channels/TestChannelKind.kt
@@ -64,7 +64,7 @@ private class ChannelViaBroadcast<E>(
     override fun cancel(cause: CancellationException?) = sub.cancel(cause)
 
     // implementing hidden method anyway, so can cast to an internal class
-    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")
+    @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")
     override fun cancel(cause: Throwable?): Boolean = (sub as AbstractChannel).cancelInternal(cause)
 
     override val onReceive: SelectClause1<E>
diff --git a/kotlinx-coroutines-core/js/src/Exceptions.kt b/kotlinx-coroutines-core/js/src/Exceptions.kt
@@ -55,7 +55,11 @@ internal fun IllegalStateException(message: String, cause: Throwable?) =
     IllegalStateException(message.withCause(cause))
 
 private fun String?.withCause(cause: Throwable?) =
-    if (cause == null) this else "$this; caused by $cause"
+    when {
+        cause == null -> this
+        this == null -> "caused by $cause"
+        else -> "$this; caused by $cause"
+    }
 
 @Suppress("NOTHING_TO_INLINE")
 internal actual inline fun Throwable.addSuppressedThrowable(other: Throwable) { /* empty */ }
diff --git a/kotlinx-coroutines-core/native/src/Exceptions.kt b/kotlinx-coroutines-core/native/src/Exceptions.kt
@@ -55,7 +55,11 @@ internal fun IllegalStateException(message: String, cause: Throwable?) =
     IllegalStateException(message.withCause(cause))
 
 private fun String?.withCause(cause: Throwable?) =
-    if (cause == null) this else "$this; caused by $cause"
+    when {
+        cause == null -> this
+        this == null -> "caused by $cause"
+        else -> "$this; caused by $cause"
+    }
 
 @Suppress("NOTHING_TO_INLINE")
 internal actual inline fun Throwable.addSuppressedThrowable(other: Throwable) { /* empty */ }

Original file line number	Diff line number	Diff line change
`@@ -73,7 +73,7 @@ public fun <T> Deferred<T>.asCompletableFuture(): CompletableFuture<T> {`
`73`	`73`	`val future = CompletableFuture<T>()`
`74`	`74`	`future.whenComplete { _, exception ->`
`75`	`75`	`cancel(exception?.let {`
`76`		`- it as? CancellationException ?: CancellationException("Future failed", it)`
	`76`	`+ it as? CancellationException ?: CancellationException("CompletableFuture was completed exceptionally", it)`
`77`	`77`	`})`
`78`	`78`	`}`
`79`	`79`	`invokeOnCompletion {`
Original file line number	Diff line number	Diff line change
`@@ -655,7 +655,7 @@ internal abstract class AbstractChannel<E> : AbstractSendChannel<E>(), Channel<E`
`655`	`655`	`return if (result === POLL_FAILED) null else receiveOrNullResult(result)`
`656`	`656`	`}`
`657`	`657`
`658`		`- @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")`
	`658`	`+ @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")`
`659`	`659`	`final override fun cancel(cause: Throwable?): Boolean =`
`660`	`660`	`cancelInternal(cause)`
`661`	`661`
Original file line number	Diff line number	Diff line change
`@@ -67,7 +67,7 @@ internal class ArrayBroadcastChannel<E>(`
`67`	`67`	`return true`
`68`	`68`	`}`
`69`	`69`
`70`		`- @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")`
	`70`	`+ @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")`
`71`	`71`	`override fun cancel(cause: Throwable?): Boolean =`
`72`	`72`	`cancelInternal(cause)`
`73`	`73`
Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@ internal open class ChannelCoroutine<E>(`
`19`	`19`	`cancelInternal(null)`
`20`	`20`	`}`
`21`	`21`
`22`		`- @Deprecated(level = DeprecationLevel.HIDDEN, message = "Binary compatibility only")`
	`22`	`+ @Deprecated(level = DeprecationLevel.HIDDEN, message = "Since 1.2.0, binary compatibility with versions <= 1.1.x")`
`23`	`23`	`final override fun cancel(cause: Throwable?): Boolean =`
`24`	`24`	`cancelInternal(cause)`
`25`	`25`