Following internal API is removed from public declarations:

  * ArrayBroadcastChannel
  * NonDisposableHandle
  * handleCoroutineException
  * JobCancellationException
  * withTimeout and delay with TimeUnit

Author: qwwdfsad

common/kotlinx-coroutines-core-common/src/CompletedExceptionally.kt

@@ -14,7 +14,7 @@ import kotlin.coroutines.experimental.*
  * **Note: cannot be internal until we get rid of MutableDelegateContinuation in IO**
  *
  * @param cause the exceptional completion cause. It's either original exceptional cause
- *        or artificial JobCancellationException if no cause was provided
+ *        or artificial [CancellationException] if no cause was provided
  * @suppress **This is unstable API and it is subject to change.**
  */
 open class CompletedExceptionally(
@@ -29,7 +29,7 @@ open class CompletedExceptionally(
  * **Note: This class cannot be used outside of internal coroutines framework**.
  *
  * @param job the job that was cancelled.
- * @param cause the exceptional completion cause. If `cause` is null, then a [JobCancellationException] is created.
+ * @param cause the exceptional completion cause. If `cause` is null, then a [CancellationException] is created.
  * @suppress **This is unstable API and it is subject to change.**
  */
 internal class Cancelled(
@@ -43,8 +43,8 @@ internal class Cancelled(
  * **Note: This class cannot be used outside of internal coroutines framework**.
  *
  * @param continuation the continuation that was cancelled.
- * @param cause the exceptional completion cause. If `cause` is null, then a [JobCancellationException]
- *        if created on first get from [exception] property.
+ * @param cause the exceptional completion cause. If `cause` is null, then a [CancellationException]
+ *        if created on first access to [exception] property.
  * @suppress **This is unstable API and it is subject to change.**
  */
 public class CancelledContinuation(

common/kotlinx-coroutines-core-common/src/CoroutineExceptionHandler.kt

@@ -22,7 +22,7 @@ internal expect fun handleCoroutineExceptionImpl(context: CoroutineContext, exce
  * Otherwise all instances of [CoroutineExceptionHandler] found via [ServiceLoader] and [Thread.uncaughtExceptionHandler] are invoked
  */
 @JvmOverloads // binary compatibility
-@InternalCoroutinesApi // todo: review KDoc use
+@InternalCoroutinesApi
 public fun handleCoroutineException(context: CoroutineContext, exception: Throwable, caller: Job? = null) {
     // if exception handling fails, make sure the original exception is not lost
     try {
@@ -72,11 +72,9 @@ public inline fun CoroutineExceptionHandler(crossinline handler: (CoroutineConte
  *   (because that is the supposed mechanism to cancel the running coroutine)
  * * Otherwise:
  *     * if there is a [Job] in the context, then [Job.cancel] is invoked;
- *     * all instances of [CoroutineExceptionHandler] found via [ServiceLoader] are invoked;
- *     * and current thread's [Thread.uncaughtExceptionHandler] is invoked.
- *
- * See [handleCoroutineException].
- */
+ *     * Otherwise, all instances of [CoroutineExceptionHandler] found via [ServiceLoader]
+ *     * and current thread's [Thread.uncaughtExceptionHandler] are invoked.
+ **/
 public interface CoroutineExceptionHandler : CoroutineContext.Element {
     /**
      * Key for [CoroutineExceptionHandler] instance in the coroutine context.
@@ -85,7 +83,7 @@ public interface CoroutineExceptionHandler : CoroutineContext.Element {
 
     /**
      * Handles uncaught [exception] in the given [context]. It is invoked
-     * if coroutine has an uncaught exception. See [handleCoroutineException].
+     * if coroutine has an uncaught exception.
      */
     public fun handleException(context: CoroutineContext, exception: Throwable)
 }

common/kotlinx-coroutines-core-common/src/CoroutineScope.kt

@@ -169,7 +169,7 @@ object GlobalScope : CoroutineScope {
  * 2) If `doSomeWork` throws an exception, then `async` task is cancelled and `loadDataForUI` rethrows that exception.
  * 3) If outer scope of `loadDataForUI` is cancelled, both started `async` and `withContext` are cancelled.
  *
- * Method may throw [JobCancellationException] if the current job was cancelled externally
+ * Method may throw [CancellationException] if the current job was cancelled externally
  * or may throw the corresponding unhandled [Throwable] if there is any unhandled exception in this scope
  * (for example, from a crashed coroutine that was started with [launch][CoroutineScope.launch] in this scope).
  */

common/kotlinx-coroutines-core-common/src/Delay.kt

@@ -109,7 +109,6 @@ public suspend fun delay(timeMillis: Long) {
  *
  * @suppress **Deprecated**: Replace with `delay(unit.toMillis(time))`
  */
-// todo: review usage in Guides and samples
 @Deprecated(
     message = "Replace with delay(unit.toMillis(time))",
     replaceWith = ReplaceWith("delay(unit.toMillis(time))")

common/kotlinx-coroutines-core-common/src/Exceptions.common.kt

@@ -12,7 +12,7 @@ public expect open class CancellationException(message: String?) : IllegalStateE
 /**
  * @suppress **Deprecated**: Replace with [CancellationException].
  */
-@InternalCoroutinesApi // todo: review usage from docs and examples
+@InternalCoroutinesApi
 @Deprecated(message = "Replace with CancellationException", replaceWith = ReplaceWith("CancellationException"))
 public expect class JobCancellationException(
     message: String,

common/kotlinx-coroutines-core-common/src/Job.kt

@@ -123,8 +123,8 @@ public interface Job : CoroutineContext.Element {
      *
      * 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
+     * was cancelled without a cause, or had completed normally), an instance of [CancellationException] is
+     * returned. The [CancellationException.cause] of the resulting [CancellationException] references
      * the original cancellation cause that was passed to [cancel] function.
      *
      * This function throws [IllegalStateException] when invoked on a job that has not
@@ -333,8 +333,8 @@ public interface Job : CoroutineContext.Element {
      * @param onCancelling when `true`, then the [handler] is invoked as soon as this job transitions to _cancelling_ state;
      *        when `false` then the [handler] is invoked only when it transitions to _completed_ state.
      * @param invokeImmediately when `true` and this job is already in the desired state (depending on [onCancelling]),
-     *        then the [handler] is immediately and synchronously invoked and [NonDisposableHandle] is returned;
-     *        when `false` then [NonDisposableHandle] is returned, but the [handler] is not invoked.
+     *        then the [handler] is immediately and synchronously invoked and no-op [DisposableHandle] is returned;
+     *        when `false` then no-op [DisposableHandle] is returned, but the [handler] is not invoked.
      * @param handler the handler.
      * 
      * @suppress **This an internal API and should not be used from general code.**
@@ -531,7 +531,7 @@ public suspend fun Job.join() = this.join()
  * No-op implementation of [DisposableHandle].
  * @suppress **This an internal API and should not be used from general code.**
  */
-@InternalCoroutinesApi // todo: review references from KDocs
+@InternalCoroutinesApi
 public object NonDisposableHandle : DisposableHandle {
     /** Does not do anything. */
     override fun dispose() {}

common/kotlinx-coroutines-core-common/src/JobSupport.kt

@@ -406,7 +406,7 @@ internal open class JobSupport constructor(active: Boolean) : Job, SelectClause0
 
     /**
      * Returns the cause that signals the completion of this job -- it returns the original
-     * [cancel] cause, [JobCancellationException] or **`null` if this job had completed normally**.
+     * [cancel] cause, [CancellationException] or **`null` if this job had completed normally**.
      * This function throws [IllegalStateException] when invoked for an job that has not [completed][isCompleted] nor
      * [isCancelled] yet.
      */

common/kotlinx-coroutines-core-common/src/NonCancellable.kt

@@ -72,7 +72,6 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
     override fun getCancellationException(): CancellationException = throw IllegalStateException("This job is always active")
 
     /**
-     * Always returns [NonDisposableHandle].
      * @suppress **This an internal API and should not be used from general code.**
      */
     @Suppress("OverridingDeprecatedMember")
@@ -81,7 +80,6 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
         NonDisposableHandle
 
     /**
-     * Always returns [NonDisposableHandle].
      * @suppress **This an internal API and should not be used from general code.**
      */
     @Suppress("OverridingDeprecatedMember")
@@ -90,7 +88,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
         NonDisposableHandle
 
     /**
-     * Always returns [NonDisposableHandle].
+     * Always returns no-op handle.
      * @suppress **This an internal API and should not be used from general code.**
      */
     @Suppress("OverridingDeprecatedMember")
@@ -99,7 +97,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
         NonDisposableHandle
 
     /**
-     * Always returns [NonDisposableHandle].
+     * Always returns no-op handle.
      * @suppress **This an internal API and should not be used from general code.**
      */
     @InternalCoroutinesApi
@@ -129,7 +127,7 @@ public object NonCancellable : AbstractCoroutineContextElement(Job), Job {
         get() = emptySequence()
 
     /**
-     * Always returns [NonDisposableHandle] and does not do anything.
+     * Always returns no-op handle and does not do anything.
      * @suppress **This an internal API and should not be used from general code.**
      */
     @Suppress("OverridingDeprecatedMember")

common/kotlinx-coroutines-core-common/src/Scheduled.kt

@@ -31,7 +31,6 @@ public suspend fun <T> withTimeout(time: Int, block: suspend CoroutineScope.() -
  *
  * @suppress **Deprecated**: Replace with `withTimeout(unit.toMillis(time), block)`
  */
-// todo: review usage in Guides and samples
 @Deprecated(
     message = "Replace with withTimeout(unit.toMillis(time), block)",
     replaceWith = ReplaceWith("withTimeout(unit.toMillis(time), block)")
@@ -62,7 +61,6 @@ public suspend fun <T> withTimeoutOrNull(time: Int, block: suspend CoroutineScop
  * @param unit timeout unit (milliseconds by default)
  * @suppress **Deprecated**: Replace with `withTimeoutOrNull(unit.toMillis(time), block)`
  */
-// todo: review usage in Guides and samples
 @Deprecated(
     message = "Replace with withTimeoutOrNull(unit.toMillis(time), block)",
     replaceWith = ReplaceWith("withTimeoutOrNull(unit.toMillis(time), block)")

common/kotlinx-coroutines-core-common/src/channels/ArrayBroadcastChannel.kt

@@ -24,7 +24,7 @@ import kotlinx.coroutines.experimental.selects.*
  *
  * @suppress **This an internal API and should not be used from general code.**
  */
-@InternalCoroutinesApi // todo: review KDoc refs
+@InternalCoroutinesApi
 public class ArrayBroadcastChannel<E>
 @Deprecated(
     "Replace with BroadcastChannel factory function",

common/kotlinx-coroutines-core-common/src/channels/Broadcast.kt

@@ -66,7 +66,7 @@ public fun <E> broadcast(
  * the resulting channel becomes _failed_, so that any attempt to receive from such a channel throws exception.
  *
  * The kind of the resulting channel depends on the specified [capacity] parameter:
- * * when `capacity` positive (1 by default), but less than [UNLIMITED] -- uses [ArrayBroadcastChannel]
+ * * when `capacity` positive (1 by default), but less than [UNLIMITED] -- uses `ArrayBroadcastChannel` with a buffer of given capacity,
  * * when `capacity` is [CONFLATED] -- uses [ConflatedBroadcastChannel] that conflates back-to-back sends;
  * * otherwise -- throws [IllegalArgumentException].
  *

common/kotlinx-coroutines-core-common/src/channels/BroadcastChannel.kt

@@ -73,7 +73,7 @@ public interface BroadcastChannel<E> : SendChannel<E> {
  * Creates a broadcast channel with the specified buffer capacity.
  *
  * The resulting channel type depends on the specified [capacity] parameter:
- * * when `capacity` positive, but less than [UNLIMITED] -- creates [ArrayBroadcastChannel]
+ * * when `capacity` positive, but less than [UNLIMITED] -- creates `ArrayBroadcastChannel` with a buffer of given capacity.
  *   **Note:** this channel looses all items that are send to it until the first subscriber appears;
  * * when `capacity` is [CONFLATED] -- creates [ConflatedBroadcastChannel] that conflates back-to-back sends;
  * * otherwise -- throws [IllegalArgumentException].

common/kotlinx-coroutines-core-common/src/internal/Concurrent.common.kt

@@ -5,7 +5,7 @@
 package kotlinx.coroutines.experimental.internal
 
 /**
- * Special kind of list intended to be used as collection of subscribers in [ArrayBroadcastChannel]
+ * Special kind of list intended to be used as collection of subscribers in `ArrayBroadcastChannel`
  * On JVM it's CopyOnWriteList and on JS it's MutableList.
  *
  * Note that this alias is intentionally not named as CopyOnWriteList to avoid accidental misusage outside of ArrayBroadcastChannel

common/kotlinx-coroutines-core-common/test/CoroutinesTest.kt

@@ -238,7 +238,7 @@ class CoroutinesTest : TestBase() {
         // now we have a failed job with TestException
         finish(3)
         try {
-            job.cancelAndJoin() // join should crash on child's exception but it will be wrapped into JobCancellationException
+            job.cancelAndJoin() // join should crash on child's exception but it will be wrapped into CancellationException
         } catch (e: Throwable) {
             e as CancellationException // type assertion
             assertTrue(e.cause is TestException)

core/kotlinx-coroutines-core/src/Builders.kt

@@ -28,7 +28,7 @@ import kotlin.coroutines.experimental.*
  *
  * See [newCoroutineContext][CoroutineScope.newCoroutineContext] for a description of debugging facilities that are available for newly created coroutine.
  *
- * @param context context of the coroutine. The default value is an implementation of [EventLoop].
+ * @param context context of the coroutine. The default value is an event loop on current thread.
  * @param block the coroutine code.
  */
 @Throws(InterruptedException::class)

core/kotlinx-coroutines-core/src/Exceptions.kt

@@ -19,7 +19,7 @@ public actual class CompletionHandlerException actual constructor(
  * Thrown by cancellable suspending functions if the [Job] of the coroutine is cancelled while it is suspending.
  * It indicates _normal_ cancellation of a coroutine.
  * **It is not printed to console/log by default uncaught exception handler**.
- * (see [handleCoroutineException]).
+ * See [CoroutineExceptionHandler]
 */
 public actual typealias CancellationException = java.util.concurrent.CancellationException
 
@@ -30,7 +30,7 @@ public actual typealias CancellationException = java.util.concurrent.Cancellatio
  * 
  * @suppress **Deprecated**: Replace with [CancellationException].
  */
-@InternalCoroutinesApi // todo: review usage from docs and examples
+@InternalCoroutinesApi
 @Deprecated(message = "Replace with CancellationException", replaceWith = ReplaceWith("CancellationException"))
 public actual class JobCancellationException public actual constructor(
     message: String,

integration/kotlinx-coroutines-jdk8/test/examples/simple-example-2.kt

@@ -11,7 +11,7 @@ import java.util.concurrent.*
 // this function returns a CompletableFuture using Kotlin coroutines
 fun supplyTheAnswerAsync(): CompletableFuture<Int> = GlobalScope.future {
     println("We might be doing some asynchronous IO here or something else...")
-    delay(1, TimeUnit.SECONDS) // just do a non-blocking delay
+    delay(1000) // just do a non-blocking delay
     42 // The answer!
 }
 

js/kotlinx-coroutines-core-js/src/Exceptions.kt

@@ -16,7 +16,7 @@ public actual class CompletionHandlerException public actual constructor(
  * Thrown by cancellable suspending functions if the [Job] of the coroutine is cancelled while it is suspending.
  * It indicates _normal_ cancellation of a coroutine.
  * **It is not printed to console/log by default uncaught exception handler**.
- * (see [handleCoroutineException]).
+ * (see [CoroutineExceptionHandler]).
  */
 public actual open class CancellationException actual constructor(message: String?) : IllegalStateException(message)
 

native/kotlinx-coroutines-core-native/src/Exceptions.kt

@@ -16,7 +16,7 @@ public actual class CompletionHandlerException public actual constructor(
  * Thrown by cancellable suspending functions if the [Job] of the coroutine is cancelled while it is suspending.
  * It indicates _normal_ cancellation of a coroutine.
  * **It is not printed to console/log by default uncaught exception handler**.
- * (see [handleCoroutineException]).
+ * (see [CoroutineExceptionHandler]).
  */
 public actual open class CancellationException actual constructor(message: String?) : IllegalStateException(message)