Fix typos and improve article usage in docs

Author: Inego

docs/cancellation-and-timeouts.md

@@ -38,7 +38,7 @@ This section covers coroutine cancellation and timeouts.
 In a long-running application you might need fine-grained control on your background coroutines.
 For example, a user might have closed the page that launched a coroutine and now its result
 is no longer needed and its operation can be cancelled. 
-The [launch] function returns a [Job] that can be used to cancel running coroutine:
+The [launch] function returns a [Job] that can be used to cancel the running coroutine:
 
 <div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
 

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

@@ -20,44 +20,44 @@ import kotlin.jvm.*
  *
  * The following methods are available for override:
  *
- * * [onStart] is invoked when coroutine was created in not active state and is being [started][Job.start].
- * * [onCancelling] is invoked as soon as coroutine is being cancelled for any reason (or completes).
- * * [onCompleted] is invoked when coroutine completes with a value.
- * * [onCancelled] in invoked when coroutines completes with exception (cancelled).
+ * * [onStart] is invoked when the coroutine was created in non-active state and is being [started][Job.start].
+ * * [onCancelling] is invoked as soon as the coroutine starts being cancelled for any reason (or completes).
+ * * [onCompleted] is invoked when the coroutine completes with a value.
+ * * [onCancelled] in invoked when the coroutine completes with an exception (cancelled).
  *
- * @param parentContext context of the parent coroutine.
- * @param active when `true` (by default) coroutine is created in _active_ state, when `false` in _new_ state.
+ * @param parentContext the context of the parent coroutine.
+ * @param active when `true` (by default), the coroutine is created in the _active_ state, otherwise it is created in the _new_ state.
  *               See [Job] for details.
  *
  * @suppress **This an internal API and should not be used from general code.**
  */
 @InternalCoroutinesApi
 public abstract class AbstractCoroutine<in T>(
     /**
-     * Context of the parent coroutine.
+     * The context of the parent coroutine.
      */
     @JvmField
     protected val parentContext: CoroutineContext,
     active: Boolean = true
 ) : JobSupport(active), Job, Continuation<T>, CoroutineScope {
     /**
-     * Context of this coroutine that includes this coroutine as a [Job].
+     * The context of this coroutine that includes this coroutine as a [Job].
      */
     @Suppress("LeakingThis")
     public final override val context: CoroutineContext = parentContext + this
 
     /**
-     * Context of this scope which is the same as the [context] of this coroutine.
+     * The context of this scope which is the same as the [context] of this coroutine.
      */
     public override val coroutineContext: CoroutineContext get() = context
 
     override val isActive: Boolean get() = super.isActive
 
     /**
-     * Initializes parent job from the `parentContext` of this coroutine that was passed to it during construction.
+     * Initializes the parent job from the `parentContext` of this coroutine that was passed to it during construction.
      * It shall be invoked at most once after construction after all other initialization.
      * 
-     * Invocation of this function may cause this coroutine to become cancelled if parent is already cancelled,
+     * Invocation of this function may cause this coroutine to become cancelled if the parent is already cancelled,
      * in which case it synchronously invokes all the corresponding handlers.
      * @suppress **This is unstable API and it is subject to change.**
      */
@@ -66,7 +66,7 @@ public abstract class AbstractCoroutine<in T>(
     }
 
     /**
-     * This function is invoked once when non-active coroutine (constructed with `active` set to `false)
+     * This function is invoked once when a non-active coroutine (constructed with `active` set to `false)
      * is [started][start].
      */
     protected open fun onStart() {}
@@ -76,13 +76,13 @@ public abstract class AbstractCoroutine<in T>(
     }
 
     /**
-     * This function is invoked once when job was completed normally with the specified [value],
-     * right before all the waiters for coroutine's completion are notified.
+     * This function is invoked once when the job was completed normally with the specified [value],
+     * right before all the waiters for the coroutine's completion are notified.
      */
     protected open fun onCompleted(value: T) {}
 
     /**
-     * This function is invoked once when job was cancelled with the specified [cause],
+     * This function is invoked once when the job was cancelled with the specified [cause],
      * right before all the waiters for coroutine's completion are notified.
      *
      * **Note:** the state of the coroutine might not be final yet in this function and should not be queried.

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

@@ -10,8 +10,8 @@ import kotlinx.coroutines.selects.*
 /**
  * A [Deferred] that can be completed via public functions [complete] or [cancel][Job.cancel].
  *
- * Note that [complete] functions returns `false` when this deferred value is already complete or completing,
- * while [cancel][Job.cancel] returns `true` as long the deferred is still _cancelling_ and the corresponding
+ * Note that the [complete] function returns `false` when this deferred value is already complete or completing,
+ * while [cancel][Job.cancel] returns `true` as long as the deferred is still _cancelling_ and the corresponding
  * exception is incorporated into the final [completion exception][getCompletionExceptionOrNull].
  *
  * An instance of completable deferred can be created by `CompletableDeferred()` function in _active_ state.
@@ -24,7 +24,7 @@ public interface CompletableDeferred<T> : Deferred<T> {
      * Completes this deferred value with a given [value]. The result is `true` if this deferred was
      * completed as a result of this invocation and `false` otherwise (if it was already completed).
      *
-     * Repeated invocations of this function have no effect and always produce `false`.
+     * Subsequent invocations of this function have no effect and always produce `false`.
      *
      * This function transitions this deferred into _completed_ state if it was not completed or cancelled yet.
      * However, if this deferred has children, then it transitions into _completing_ state and becomes _complete_
@@ -36,7 +36,7 @@ public interface CompletableDeferred<T> : Deferred<T> {
      * Completes this deferred value exceptionally with a given [exception]. The result is `true` if this deferred was
      * completed as a result of this invocation and `false` otherwise (if it was already completed).
      *
-     * Repeated invocations of this function have no effect and always produce `false`.
+     * Subsequent invocations of this function have no effect and always produce `false`.
      *
      * This function transitions this deferred into _cancelled_ state if it was not completed or cancelled yet.
      * However, that if this deferred has children, then it transitions into _cancelling_ state and becomes _cancelled_

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

@@ -13,7 +13,7 @@ public interface CompletableJob : Job {
      * Completes this job. The result is `true` if this job was completed as a result of this invocation and
      * `false` otherwise (if it was already completed).
      *
-     * Repeated invocations of this function have no effect and always produce `false`.
+     * Subsequent invocations of this function have no effect and always produce `false`.
      *
      * This function transitions this job into _completed- state if it was not completed or cancelled yet.
      * However, that if this job has children, then it transitions into _completing_ state and becomes _complete_
@@ -25,7 +25,7 @@ public interface CompletableJob : Job {
      * Completes this job exceptionally with a given [exception]. The result is `true` if this job was
      * completed as a result of this invocation and `false` otherwise (if it was already completed).
      *
-     * Repeated invocations of this function have no effect and always produce `false`.
+     * Subsequent invocations of this function have no effect and always produce `false`.
      *
      * This function transitions this job into _cancelled_ state if it was not completed or cancelled yet.
      * However, that if this job has children, then it transitions into _cancelling_ state and becomes _cancelled_

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

@@ -13,8 +13,8 @@ import kotlinx.coroutines.internal.*
  * wrapped into [CompletionHandlerException], and rethrown, potentially causing crash of unrelated code.
  *
  * 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_.
+ * * Cause is `null` when the job has completed normally.
+ * * Cause is an instance of [CancellationException] when the 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_.
  *

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

@@ -19,7 +19,7 @@ internal expect fun handleCoroutineExceptionImpl(context: CoroutineContext, exce
  */
 @InternalCoroutinesApi
 public fun handleCoroutineException(context: CoroutineContext, exception: Throwable) {
-    // Invoke exception handler from the context if present
+    // Invoke an exception handler from the context if present
     try {
         context[CoroutineExceptionHandler]?.let {
             it.handleException(context, exception)
@@ -29,7 +29,7 @@ public fun handleCoroutineException(context: CoroutineContext, exception: Throwa
         handleCoroutineExceptionImpl(context, handlerException(exception, t))
         return
     }
-    // If handler is not present in the context or exception was thrown, fallback to the global handler
+    // If a handler is not present in the context or an exception was thrown, fallback to the global handler
     handleCoroutineExceptionImpl(context, exception)
 }
 
@@ -54,7 +54,7 @@ public inline fun CoroutineExceptionHandler(crossinline handler: (CoroutineConte
 /**
  * An optional element in the coroutine context to handle uncaught exceptions.
  *
- * Normally, uncaught exceptions can only result from coroutines created using [launch][CoroutineScope.launch] builder.
+ * Normally, uncaught exceptions can only result from coroutines created using the [launch][CoroutineScope.launch] builder.
  * A coroutine that was created using [async][CoroutineScope.async] always catches all its exceptions and represents them
  * in the resulting [Deferred] object.
  *

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

@@ -15,10 +15,10 @@ import kotlin.coroutines.intrinsics.*
  * to automatically propagate both context elements and cancellation.
  *
  * The best ways to obtain a standalone instance of the scope are [CoroutineScope()] and [MainScope()] factory functions.
- * Additional context elements can be appended to the scope using [plus][CoroutineScope.plus] operator.
+ * Additional context elements can be appended to the scope using the [plus][CoroutineScope.plus] operator.
  *
  * Manual implementation of this interface is not recommended, implementation by delegation should be preferred instead.
- * By convention, [context of the scope][CoroutineScope.coroutineContext] should contain an instance of a [job][Job] to enforce structured concurrency.
+ * By convention, the [context of a scope][CoroutineScope.coroutineContext] should contain an instance of a [job][Job] to enforce structured concurrency.
  *
  * Every coroutine builder (like [launch][CoroutineScope.launch], [async][CoroutineScope.async], etc)
  * and every scoping function (like [coroutineScope], [withContext], etc) provides _its own_ scope
@@ -164,8 +164,8 @@ public object GlobalScope : CoroutineScope {
  * }
  * ```
  *
- * Semantics of the scope in this example:
- * 1) `showSomeData` returns as soon as data is loaded and displayed in the UI.
+ * The scope in this example has the following semantics:
+ * 1) `showSomeData` returns as soon as the data is loaded and displayed in the UI.
  * 2) If `doSomeWork` throws an exception, then the `async` task is cancelled and `showSomeData` rethrows that exception.
  * 3) If the outer scope of `showSomeData` is cancelled, both started `async` and `withContext` blocks are cancelled.
  * 4) If the `async` block fails, `withContext` will be cancelled.

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

@@ -60,7 +60,7 @@ public enum class CoroutineStart {
 
     /**
      * Immediately executes the coroutine until its first suspension point _in the current thread_ as if the
-     * coroutine was started using [Dispatchers.Unconfined]. However, when coroutine is resumed from suspension
+     * coroutine was started using [Dispatchers.Unconfined]. However, when the coroutine is resumed from suspension
      * it is dispatched according to the [CoroutineDispatcher] in its context.
      *
      * This is similar to [ATOMIC] in the sense that coroutine starts executing even if it was already cancelled,

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

@@ -7,20 +7,20 @@ package kotlinx.coroutines
 import kotlinx.coroutines.selects.*
 
 /**
- * Deferred value is a non-blocking cancellable future — it is a [Job] that has a result.
+ * Deferred value is a non-blocking cancellable future — it is a [Job] with a result.
  *
- * It is created with [async][CoroutineScope.async] coroutine builder or via constructor of [CompletableDeferred] class.
+ * It is created with the [async][CoroutineScope.async] coroutine builder or via the constructor of [CompletableDeferred] class.
  * It is in [active][isActive] state while the value is being computed.
  *
- * Deferred value has the same state machine as the [Job] with additional convenience methods to retrieve
- * successful or failed result of the computation that was carried out. The result of the deferred is
+ * `Deferred` has the same state machine as the [Job] with additional convenience methods to retrieve
+ * the successful or failed result of the computation that was carried out. The result of the deferred is
  * available when it is [completed][isCompleted] and can be retrieved by [await] method, which throws
- * exception if the deferred had failed.
- * Note that a _cancelled_ deferred is also considered to be completed.
+ * an exception if the deferred had failed.
+ * Note that a _cancelled_ deferred is also considered as completed.
  * The corresponding exception can be retrieved via [getCompletionExceptionOrNull] from a completed instance of deferred.
  *
  * Usually, a deferred value is created in _active_ state (it is created and started).
- * However, [async][CoroutineScope.async] coroutine builder has an optional `start` parameter that creates a deferred value in _new_ state
+ * However, the [async][CoroutineScope.async] coroutine builder has an optional `start` parameter that creates a deferred value in _new_ state
  * when this parameter is set to [CoroutineStart.LAZY].
  * Such a deferred can be be made _active_ by invoking [start], [join], or [await].
  *

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

@@ -19,8 +19,8 @@ import kotlin.jvm.*
  * 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
+ * of a parent leads to immediate cancellation of all its [children]. Failure or cancellation of a child
+ * with an exception other than [CancellationException] immediately cancels its parent. This way, a 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
@@ -255,13 +255,13 @@ public interface Job : CoroutineContext.Element {
 
     /**
      * Registers handler that is **synchronously** invoked once on completion of this job.
-     * When job is already complete, then the handler is immediately invoked
-     * with a job's exception or cancellation cause or `null`. Otherwise, handler will be invoked once when this
+     * When the job is already complete, then the handler is immediately invoked
+     * with the job's exception or cancellation cause or `null`. Otherwise, the handler will be invoked once when this
      * job 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_.
+     * * Cause is `null` when the job has completed normally.
+     * * Cause is an instance of [CancellationException] when the 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_.
      *
@@ -281,13 +281,13 @@ public interface Job : CoroutineContext.Element {
 
     /**
      * 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.
+     * when the job was already cancelled and is completed its execution, then the handler is immediately invoked
+     * with the job's cancellation cause or `null` unless [invokeImmediately] is set to false.
      * 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_.
+     * * Cause is `null` when the job has completed normally.
+     * * Cause is an instance of [CancellationException] when the 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_.
      *