Reviewed and cleanup usage of "fail" word in comments and method names

Author: elizarov

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

@@ -13,7 +13,9 @@ public expect open class CancellationException(message: String?) : IllegalStateE
  * @suppress **Deprecated**: Replace with [CancellationException].
  */
 @InternalCoroutinesApi
-@Deprecated(message = "Replace with CancellationException", replaceWith = ReplaceWith("CancellationException"))
+@Deprecated( // todo: remove deprecated, make it internal
+    message = "Replace with CancellationException",
+    replaceWith = ReplaceWith("CancellationException"))
 public expect class JobCancellationException(
     message: String,
     cause: Throwable?,

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

@@ -15,8 +15,12 @@ import kotlin.coroutines.experimental.*
 
 /**
  * A background job. Conceptually, a job is a cancellable thing with a life-cycle that
- * culminates in its completion. Jobs can be arranged into parent-child hierarchies where cancellation
- * of parent lead to an immediate cancellation of all its [children] and vice versa.
+ * culminates in its completion.
+ *
+ * Jobs can be arranged into parent-child hierarchies where cancellation
+ * of parent lead to an immediate cancellation of all its [children]. Failure or cancellation of a child
+ * with an exception other than [CancellationException] immediately cancels its parent. This way, parent
+ * can [cancel] its own children (including all their children recursively) without cancelling itself.
  *
  * The most basic instances of [Job] are created with [launch][CoroutineScope.launch] coroutine builder or with a
  * `Job()` factory function.
@@ -38,7 +42,7 @@ import kotlin.coroutines.experimental.*
  * that provide an optional `start` parameter create a coroutine in _new_ state when this parameter is set to
  * [CoroutineStart.LAZY]. Such a job can be made _active_ by invoking [start] or [join].
  *
- * A job is _active_ while the coroutine is working. Failure of the job makes it _cancelling_.
+ * A job is _active_ while the coroutine is working. Failure of the job with exception makes it _cancelling_.
  * A job can be cancelled it at any time with [cancel] function that forces it to transition to
  * _cancelling_ state immediately. The job becomes _cancelled_  when it finishes executing it work.
  *
@@ -47,7 +51,7 @@ import kotlin.coroutines.experimental.*
  * +-----+ start  +--------+ complete   +-------------+  finish  +-----------+
  * | New | -----> | Active | ---------> | Completing  | -------> | Completed |
  * +-----+        +--------+            +-------------+          +-----------+
- *                  |        cancel        |
+ *                  |  cancel / fail       |
  *                  |     +----------------+
  *                  |     |
  *                  V     V
@@ -65,6 +69,12 @@ import kotlin.coroutines.experimental.*
  * Note, that _completing_ state is purely internal to the job. For an outside observer a _completing_ job is still
  * active, while internally it is waiting for its children.
  *
+ * Normal cancellation of a job is distinguished from its failure by the type of its cancellation exception cause.
+ * If the cause of cancellation is [CancellationException], then the job is considered to be _cancelled normally_.
+ * This usually happens when [cancel] is invoked without additional parameters. If the cause of cancellation is
+ * a different exception, then the job is considered to have _failed_. This usually happens when the code of the job
+ * encounters some problem and throws an exception.
+ *
  * All functions on this interface and on all interfaces derived from it are **thread-safe** and can
  * be safely invoked from concurrent coroutines without external synchronization.
  */
@@ -94,25 +104,31 @@ public interface Job : CoroutineContext.Element {
     // ------------ state query ------------
 
     /**
-     * Returns `true` when this job is active -- it was already started and has not completed or failed yet.
+     * Returns `true` when this job is active -- it was already started and has not completed nor was cancelled yet.
      * The job that is waiting for its [children] to complete is still considered to be active if it
-     * has not failed and was not cancelled.
+     * was not cancelled nor failed.
+     *
+     * See [Job] documentation for more details on job states.
      */
     public val isActive: Boolean
 
     /**
-     * Returns `true` when this job has completed for any reason. A job that has failed or cancelled
+     * Returns `true` when this job has completed for any reason. A job that was cancelled or failed
      * and has finished its execution is also considered complete. Job becomes complete only after
      * all its [children] complete.
+     *
+     * See [Job] documentation for more details on job states.
      */
     public val isCompleted: Boolean
 
     /**
      * Returns `true` if this job was cancelled for any reason, either by explicit invocation of [cancel] or
-     * because it had failed or its children or parent was cancelled.
+     * because it had failed or its child or parent was cancelled.
      * In the general case, it does not imply that the
      * job has already [completed][isCompleted], because it may still be finishing whatever it was doing and
      * waiting for its [children] to complete.
+     *
+     * See [Job] documentation for more details on cancellation and failures.
      */
     public val isCancelled: Boolean
 
@@ -203,7 +219,7 @@ public interface Job : CoroutineContext.Element {
      *
      * A parent-child relation has the following effect:
      * * Cancellation of parent with [cancel] or its exceptional completion (failure)
-     *   immediately fails all its children.
+     *   immediately cancels all its children.
      * * Parent cannot complete until all its children are complete. Parent waits for all its children to
      *   complete in _completing_ or _cancelling_ states.
      *
@@ -300,20 +316,20 @@ public interface Job : CoroutineContext.Element {
     public fun invokeOnCompletion(handler: CompletionHandler): DisposableHandle
 
     /**
-     * Registers handler that is **synchronously** invoked once on failure or completion of this job.
-     * When job is already failing or complete, then the handler is immediately invoked
+     * Registers handler that is **synchronously** invoked once on cancellation or completion of this job.
+     * When job was already cancelled and is completed its execution, then the handler is immediately invoked
      * with a job's cancellation cause or `null` unless [invokeImmediately] is set to false.
-     * Otherwise, handler will be invoked once when this job is failing or is complete.
+     * Otherwise, handler will be invoked once when this job is cancelled or is complete.
      *
      * The meaning of `cause` that is passed to the handler:
      * * Cause is `null` when job has completed normally.
      * * Cause is an instance of [CancellationException] when job was cancelled _normally_.
      *   **It should not be treated as an error**. In particular, it should not be reported to error logs.
      * * Otherwise, the job had _failed_.
      *
-     * Invocation of this handler on a transition to a _failing_ state
+     * Invocation of this handler on a transition to a _cancelling_ state
      * is controlled by [onCancelling] boolean parameter.
-     * The handler is invoked when the job is failing when [onCancelling] parameter is set to `true`.
+     * The handler is invoked when the job becomes _cancelling_ if [onCancelling] parameter is set to `true`.
      *
      * The resulting [DisposableHandle] can be used to [dispose][DisposableHandle.dispose] the
      * registration of this handler and release its memory if its invocation is no longer needed.
@@ -328,7 +344,7 @@ public interface Job : CoroutineContext.Element {
      * This function should not be used in general application code.
      * Implementations of `CompletionHandler` must be fast and _lock-free_.
      *
-     * @param onCancelling when `true`, then the [handler] is invoked as soon as this job transitions to _failing_ state;
+     * @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 no-op [DisposableHandle] is returned;
@@ -391,32 +407,32 @@ public inline fun DisposableHandle(crossinline block: () -> Unit) =
 // -------------------- Parent-child communication --------------------
 
 /**
- * A reference that parent receives from its child so that it can report its failure.
+ * A reference that parent receives from its child so that it can report its cancellation.
  *
  * @suppress **This is unstable API and it is subject to change.**
  */
 internal interface ChildJob : Job {
     /**
-     * Parent is reporting failure to the child by invoking this method.
-     * Child finds the failure cause using [getCancellationException] of the [parentJob].
-     * This method does nothing is the child is already failing.
+     * Parent is cancelling its child by invoking this method.
+     * Child finds the cancellation cause using [getCancellationException] of the [parentJob].
+     * This method does nothing is the child is already being cancelled.
      *
      * @suppress **This is unstable API and it is subject to change.**
      */
     public fun parentCancelled(parentJob: Job)
 }
 
 /**
- * A handle that child keep onto its parent so that it is able to report its failure.
+ * A handle that child keep onto its parent so that it is able to report its cancellation.
  *
  * @suppress **This is unstable API and it is subject to change.**
  */
 internal interface ChildHandle : DisposableHandle {
     /**
-     * Child is reporting failure to the parent by invoking this method.
+     * Child is cancelling its parent by invoking this method.
      * This method is invoked by the child twice. The first time child report its root cause as soon as possible,
-     * so that all its siblings and the parent can start finishing their work asap on failure. The second time
-     * child invokes this method when it had aggregated and determined its final termination cause.
+     * so that all its siblings and the parent can start cancelling their work asap. The second time
+     * child invokes this method when it had aggregated and determined its final cancellation cause.
      *
      * @suppress **This is unstable API and it is subject to change.**
      */