Fix more typos

Author: Inego

docs/basics.md

@@ -119,7 +119,7 @@ World!
 -->
 
 The result is the same, but this code uses only non-blocking [delay]. 
-The main thread, that invokes `runBlocking`, _blocks_ until the coroutine inside `runBlocking` completes. 
+The main thread invoking `runBlocking` _blocks_ until the coroutine inside `runBlocking` completes. 
 
 This example can be also rewritten in a more idiomatic way, using `runBlocking` to wrap 
 the execution of the main function:
@@ -151,7 +151,7 @@ World!
 Here `runBlocking<Unit> { ... }` works as an adaptor that is used to start the top-level main coroutine. 
 We explicitly specify its `Unit` return type, because a well-formed `main` function in Kotlin has to return `Unit`.
 
-This is also a way to write unit-tests for suspending functions:
+This is also a way to write unit tests for suspending functions:
 
 <!--- INCLUDE
 import kotlinx.coroutines.*
@@ -209,11 +209,11 @@ the background job in any way. Much better.
 ### Structured concurrency
 
 There is still something to be desired for practical usage of coroutines. 
-When we use `GlobalScope.launch` we create a top-level coroutine. Even though it is light-weight, it still 
+When we use `GlobalScope.launch`, we create a top-level coroutine. Even though it is light-weight, it still 
 consumes some memory resources while it runs. If we forget to keep a reference to the newly launched 
 coroutine it still runs. What if the code in the coroutine hangs (for example, we erroneously
 delay for too long), what if we launched too many coroutines and ran out of memory? 
-Having to manually keep a reference to all the launched coroutines and [join][Job.join] them is error-prone. 
+Having to manually keep references to all the launched coroutines and [join][Job.join] them is error-prone. 
 
 There is a better solution. We can use structured concurrency in our code. 
 Instead of launching coroutines in the [GlobalScope], just like we usually do with threads (threads are always global), 

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

@@ -18,13 +18,13 @@ import kotlin.jvm.*
 // --------------- launch ---------------
 
 /**
- * Launches new coroutine without blocking current thread and returns a reference to the coroutine as a [Job].
+ * Launches a new coroutine without blocking the current thread and returns a reference to the coroutine as a [Job].
  * The coroutine is cancelled when the resulting job is [cancelled][Job.cancel].
  *
- * Coroutine context is inherited from a [CoroutineScope], additional context elements can be specified with [context] argument.
+ * The coroutine context is inherited from a [CoroutineScope]. Additional context elements can be specified with [context] argument.
  * If the context does not have any dispatcher nor any other [ContinuationInterceptor], then [Dispatchers.Default] is used.
  * The parent job is inherited from a [CoroutineScope] as well, but it can also be overridden
- * with corresponding [coroutineContext] element.
+ * with a corresponding [coroutineContext] element.
  *
  * By default, the coroutine is immediately scheduled for execution.
  * Other start options can be specified via `start` parameter. See [CoroutineStart] for details.

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

@@ -116,7 +116,7 @@ public val CoroutineScope.isActive: Boolean
  * and are not cancelled prematurely.
  * Another use of the global scope is operators running in [Dispatchers.Unconfined], which don't have any job associated with them.
  *
- * Application code usually should use application-defined [CoroutineScope], using
+ * Application code usually should use an application-defined [CoroutineScope]. Using
  * [async][CoroutineScope.async] or [launch][CoroutineScope.launch]
  * on the instance of [GlobalScope] is highly discouraged.
  *
@@ -140,14 +140,14 @@ public object GlobalScope : CoroutineScope {
 }
 
 /**
- * Creates new [CoroutineScope] and calls the specified suspend block with this scope.
+ * Creates a [CoroutineScope] and calls the specified suspend block with this scope.
  * The provided scope inherits its [coroutineContext][CoroutineScope.coroutineContext] from the outer scope, but overrides
- * context's [Job].
+ * the context's [Job].
  *
- * This function is designed for a _parallel decomposition_ of work. When any child coroutine in this scope fails,
+ * This function is designed for _parallel decomposition_ of work. When any child coroutine in this scope fails,
  * this scope fails and all the rest of the children are cancelled (for a different behavior see [supervisorScope]).
- * This function returns as soon as given block and all its children coroutines are completed.
- * Example of the scope usages looks like this:
+ * This function returns as soon as the given block and all its children coroutines are completed.
+ * A usage example of a scope looks like this:
  *
  * ```
  * suspend fun showSomeData() = coroutineScope {
@@ -166,12 +166,12 @@ 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.
- * 2) If `doSomeWork` throws an exception, then `async` task is cancelled and `showSomeData` rethrows that exception.
- * 3) If outer scope of `showSomeData` is cancelled, both started `async` and `withContext` blocks are cancelled.
- * 4) If `async` block fails, `withContext` will be cancelled.
+ * 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.
  *
- * 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
+ * The method may throw a [CancellationException] if the current job was cancelled externally
+ * or may throw a 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).
  */
 public suspend fun <R> coroutineScope(block: suspend CoroutineScope.() -> R): R =
@@ -181,7 +181,7 @@ public suspend fun <R> coroutineScope(block: suspend CoroutineScope.() -> R): R
     }
 
 /**
- * Creates [CoroutineScope] that wraps the given coroutine [context].
+ * Creates a [CoroutineScope] that wraps the given coroutine [context].
  *
  * If the given [context] does not contain a [Job] element, then a default `Job()` is created.
  * This way, cancellation or failure or any child coroutine in this scope cancels all the other children,

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

@@ -158,7 +158,7 @@ public interface Job : CoroutineContext.Element {
     /**
      * Cancels this job with an optional cancellation [cause].
      * A cause can be used to specify an error message or to provide other details on
-     * a cancellation reason for debugging purposes.
+     * the cancellation reason for debugging purposes.
      * See [Job] documentation for full explanation of cancellation machinery.
      */
     public fun cancel(cause: CancellationException? = null)
@@ -223,23 +223,23 @@ public interface Job : CoroutineContext.Element {
     // ------------ state waiting ------------
 
     /**
-     * Suspends coroutine until this job is complete. This invocation resumes normally (without exception)
+     * Suspends the coroutine until this job is complete. This invocation resumes normally (without exception)
      * when the job is complete for any reason and the [Job] of the invoking coroutine is still [active][isActive].
      * This function also [starts][Job.start] the corresponding coroutine if the [Job] was still in _new_ state.
      *
      * Note that the job becomes complete only when all its children are complete.
      *
-     * This suspending function is cancellable and **always** checks for the cancellation of invoking coroutine's Job.
+     * This suspending function is cancellable and **always** checks for a cancellation of the invoking coroutine's Job.
      * If the [Job] of the invoking coroutine is cancelled or completed when this
      * suspending function is invoked or while it is suspended, this function
      * throws [CancellationException].
      *
      * In particular, it means that a parent coroutine invoking `join` on a child coroutine that was started using
      * `launch(coroutineContext) { ... }` builder throws [CancellationException] if the child
-     * had crashed, unless a non-standard [CoroutineExceptionHandler] if installed in the context.
+     * had crashed, unless a non-standard [CoroutineExceptionHandler] is installed in the context.
      *
      * This function can be used in [select] invocation with [onJoin] clause.
-     * Use [isCompleted] to check for completion of this job without waiting.
+     * Use [isCompleted] to check for a completion of this job without waiting.
      *
      * There is [cancelAndJoin] function that combines an invocation of [cancel] and `join`.
      */
@@ -462,9 +462,9 @@ internal fun Job.disposeOnCompletion(handle: DisposableHandle): DisposableHandle
     invokeOnCompletion(handler = DisposeOnCompletion(this, handle).asHandler)
 
 /**
- * Cancels the job and suspends invoking coroutine until the cancelled job is complete.
+ * Cancels the job and suspends the invoking coroutine until the cancelled job is complete.
  *
- * This suspending function is cancellable and **always** checks for the cancellation of invoking coroutine's Job.
+ * This suspending function is cancellable and **always** checks for a cancellation of the invoking coroutine's Job.
  * If the [Job] of the invoking coroutine is cancelled or completed when this
  * suspending function is invoked or while it is suspended, this function
  * throws [CancellationException].

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

@@ -11,8 +11,8 @@ import java.util.concurrent.locks.*
 import kotlin.coroutines.*
 
 /**
- * Runs new coroutine and **blocks** current thread _interruptibly_ until its completion.
- * This function should not be used from coroutine. It is designed to bridge regular blocking code
+ * Runs a new coroutine and **blocks** the current thread _interruptibly_ until its completion.
+ * This function should not be used from a coroutine. It is designed to bridge regular blocking code
  * to libraries that are written in suspending style, to be used in `main` functions and in tests.
  *
  * The default [CoroutineDispatcher] for this builder is an internal implementation of event loop that processes continuations
@@ -21,14 +21,15 @@ import kotlin.coroutines.*
  *
  * When [CoroutineDispatcher] is explicitly specified in the [context], then the new coroutine runs in the context of
  * the specified dispatcher while the current thread is blocked. If the specified dispatcher is an event loop of another `runBlocking`,
- * then this invocation uses an outer event loop.
+ * then this invocation uses the outer event loop.
  *
  * If this blocked thread is interrupted (see [Thread.interrupt]), then the coroutine job is cancelled and
  * this `runBlocking` invocation throws [InterruptedException].
  *
- * See [newCoroutineContext][CoroutineScope.newCoroutineContext] for a description of debugging facilities that are available for newly created coroutine.
+ * See [newCoroutineContext][CoroutineScope.newCoroutineContext] for a description of debugging facilities that are available
+ * for a newly created coroutine.
  *
- * @param context context of the coroutine. The default value is an event loop on current thread.
+ * @param context the context of the coroutine. The default value is an event loop on the current thread.
  * @param block the coroutine code.
  */
 @Throws(InterruptedException::class)