Fix more typos; reword some phrases; add "job:" to textual output in … (#1154)

* Fix more typos; reword some phrases; add "job:" to textual output in examples
to better differentiate between the "main" and "job" coroutines
* Gradle knit

Author: Inego

coroutines-guide.md

@@ -17,7 +17,7 @@ The main coroutines guide has moved to the [docs folder](docs/coroutines-guide.m
   * <a name='cancelling-coroutine-execution'></a>[Cancelling coroutine execution](docs/cancellation-and-timeouts.md#cancelling-coroutine-execution)
   * <a name='cancellation-is-cooperative'></a>[Cancellation is cooperative](docs/cancellation-and-timeouts.md#cancellation-is-cooperative)
   * <a name='making-computation-code-cancellable'></a>[Making computation code cancellable](docs/cancellation-and-timeouts.md#making-computation-code-cancellable)
-  * <a name='closing-resources-with-finally'></a>[Closing resources with finally](docs/cancellation-and-timeouts.md#closing-resources-with-finally)
+  * <a name='closing-resources-with-`finally`'></a>[Closing resources with `finally`](docs/cancellation-and-timeouts.md#closing-resources-with-`finally`)
   * <a name='run-non-cancellable-block'></a>[Run non-cancellable block](docs/cancellation-and-timeouts.md#run-non-cancellable-block)
   * <a name='timeout'></a>[Timeout](docs/cancellation-and-timeouts.md#timeout)
 <!--- TOC_REF docs/composing-suspending-functions.md -->

docs/cancellation-and-timeouts.md

@@ -23,7 +23,7 @@ class CancellationTimeOutsGuideTest {
   * [Cancelling coroutine execution](#cancelling-coroutine-execution)
   * [Cancellation is cooperative](#cancellation-is-cooperative)
   * [Making computation code cancellable](#making-computation-code-cancellable)
-  * [Closing resources with finally](#closing-resources-with-finally)
+  * [Closing resources with `finally`](#closing-resources-with-`finally`)
   * [Run non-cancellable block](#run-non-cancellable-block)
   * [Timeout](#timeout)
 
@@ -49,7 +49,7 @@ fun main() = runBlocking {
 //sampleStart
     val job = launch {
         repeat(1000) { i ->
-            println("I'm sleeping $i ...")
+            println("job: I'm sleeping $i ...")
             delay(500L)
         }
     }
@@ -69,9 +69,9 @@ fun main() = runBlocking {
 It produces the following output:
 
 ```text
-I'm sleeping 0 ...
-I'm sleeping 1 ...
-I'm sleeping 2 ...
+job: I'm sleeping 0 ...
+job: I'm sleeping 1 ...
+job: I'm sleeping 2 ...
 main: I'm tired of waiting!
 main: Now I can quit.
 ```
@@ -104,7 +104,7 @@ fun main() = runBlocking {
         while (i < 5) { // computation loop, just wastes CPU
             // print a message twice a second
             if (System.currentTimeMillis() >= nextPrintTime) {
-                println("I'm sleeping ${i++} ...")
+                println("job: I'm sleeping ${i++} ...")
                 nextPrintTime += 500L
             }
         }
@@ -125,12 +125,12 @@ Run it to see that it continues to print "I'm sleeping" even after cancellation
 until the job completes by itself after five iterations.
 
 <!--- TEST 
-I'm sleeping 0 ...
-I'm sleeping 1 ...
-I'm sleeping 2 ...
+job: I'm sleeping 0 ...
+job: I'm sleeping 1 ...
+job: I'm sleeping 2 ...
 main: I'm tired of waiting!
-I'm sleeping 3 ...
-I'm sleeping 4 ...
+job: I'm sleeping 3 ...
+job: I'm sleeping 4 ...
 main: Now I can quit.
 -->
 
@@ -156,7 +156,7 @@ fun main() = runBlocking {
         while (isActive) { // cancellable computation loop
             // print a message twice a second
             if (System.currentTimeMillis() >= nextPrintTime) {
-                println("I'm sleeping ${i++} ...")
+                println("job: I'm sleeping ${i++} ...")
                 nextPrintTime += 500L
             }
         }
@@ -173,22 +173,22 @@ fun main() = runBlocking {
 
 > You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt).
 
-As you can see, now this loop is cancelled. [isActive] is an extension property that is
-available inside the code of coroutine via [CoroutineScope] object.
+As you can see, now this loop is cancelled. [isActive] is an extension property 
+available inside the coroutine via the [CoroutineScope] object.
 
 <!--- TEST
-I'm sleeping 0 ...
-I'm sleeping 1 ...
-I'm sleeping 2 ...
+job: I'm sleeping 0 ...
+job: I'm sleeping 1 ...
+job: I'm sleeping 2 ...
 main: I'm tired of waiting!
 main: Now I can quit.
 -->
 
-### Closing resources with finally
+### Closing resources with `finally`
 
 Cancellable suspending functions throw [CancellationException] on cancellation which can be handled in 
-a usual way. For example, `try {...} finally {...}` expression and Kotlin `use` function execute their
-finalization actions normally when coroutine is cancelled:
+the usual way. For example, `try {...} finally {...}` expression and Kotlin `use` function execute their
+finalization actions normally when a coroutine is cancelled:
 
 
 <div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
@@ -201,11 +201,11 @@ fun main() = runBlocking {
     val job = launch {
         try {
             repeat(1000) { i ->
-                println("I'm sleeping $i ...")
+                println("job: I'm sleeping $i ...")
                 delay(500L)
             }
         } finally {
-            println("I'm running finally")
+            println("job: I'm running finally")
         }
     }
     delay(1300L) // delay a bit
@@ -220,15 +220,15 @@ fun main() = runBlocking {
 
 > You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt).
 
-Both [join][Job.join] and [cancelAndJoin] wait for all the finalization actions to complete, 
+Both [join][Job.join] and [cancelAndJoin] wait for all finalization actions to complete, 
 so the example above produces the following output:
 
 ```text
-I'm sleeping 0 ...
-I'm sleeping 1 ...
-I'm sleeping 2 ...
+job: I'm sleeping 0 ...
+job: I'm sleeping 1 ...
+job: I'm sleeping 2 ...
 main: I'm tired of waiting!
-I'm running finally
+job: I'm running finally
 main: Now I can quit.
 ```
 
@@ -240,7 +240,7 @@ Any attempt to use a suspending function in the `finally` block of the previous
 [CancellationException], because the coroutine running this code is cancelled. Usually, this is not a 
 problem, since all well-behaving closing operations (closing a file, cancelling a job, or closing any kind of a 
 communication channel) are usually non-blocking and do not involve any suspending functions. However, in the 
-rare case when you need to suspend in the cancelled coroutine you can wrap the corresponding code in
+rare case when you need to suspend in a cancelled coroutine you can wrap the corresponding code in
 `withContext(NonCancellable) {...}` using [withContext] function and [NonCancellable] context as the following example shows:
 
 <div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
@@ -253,14 +253,14 @@ fun main() = runBlocking {
     val job = launch {
         try {
             repeat(1000) { i ->
-                println("I'm sleeping $i ...")
+                println("job: I'm sleeping $i ...")
                 delay(500L)
             }
         } finally {
             withContext(NonCancellable) {
-                println("I'm running finally")
+                println("job: I'm running finally")
                 delay(1000L)
-                println("And I've just delayed for 1 sec because I'm non-cancellable")
+                println("job: And I've just delayed for 1 sec because I'm non-cancellable")
             }
         }
     }
@@ -277,18 +277,18 @@ fun main() = runBlocking {
 > You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt).
 
 <!--- TEST
-I'm sleeping 0 ...
-I'm sleeping 1 ...
-I'm sleeping 2 ...
+job: I'm sleeping 0 ...
+job: I'm sleeping 1 ...
+job: I'm sleeping 2 ...
 main: I'm tired of waiting!
-I'm running finally
-And I've just delayed for 1 sec because I'm non-cancellable
+job: I'm running finally
+job: And I've just delayed for 1 sec because I'm non-cancellable
 main: Now I can quit.
 -->
 
 ### Timeout
 
-The most obvious reason to cancel coroutine execution in practice 
+The most obvious practical reason to cancel execution of a coroutine 
 is because its execution time has exceeded some timeout.
 While you can manually track the reference to the corresponding [Job] and launch a separate coroutine to cancel 
 the tracked one after delay, there is a ready to use [withTimeout] function that does it.
@@ -331,10 +331,10 @@ We have not seen its stack trace printed on the console before. That is because
 inside a cancelled coroutine `CancellationException` is considered to be a normal reason for coroutine completion. 
 However, in this example we have used `withTimeout` right inside the `main` function. 
 
-Because cancellation is just an exception, all the resources are closed in a usual way. 
-You can wrap the code with timeout in `try {...} catch (e: TimeoutCancellationException) {...}` block if 
-you need to do some additional action specifically on any kind of timeout or use [withTimeoutOrNull] function
-that is similar to [withTimeout], but returns `null` on timeout instead of throwing an exception:
+Since cancellation is just an exception, all resources are closed in the usual way. 
+You can wrap the code with timeout in a `try {...} catch (e: TimeoutCancellationException) {...}` block if 
+you need to do some additional action specifically on any kind of timeout or use the [withTimeoutOrNull] function
+that is similar to [withTimeout] but returns `null` on timeout instead of throwing an exception:
 
 <div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
 

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

@@ -24,7 +24,7 @@ public annotation class ExperimentalCoroutinesApi
  * Its API and semantics can and will be changed in next releases.
  *
  * Feature preview can be used to evaluate its real-world strengths and weaknesses, gather and provide feedback.
- * According to the feedback, [Flow] will be refined on its road to stabilization and promotion to stable API.
+ * According to the feedback, [Flow] will be refined on its road to stabilization and promotion to a stable API.
  */
 @MustBeDocumented
 @Retention(value = AnnotationRetention.BINARY)
@@ -44,7 +44,7 @@ public annotation class ObsoleteCoroutinesApi
 
 /**
  * Marks declarations that are **internal** in coroutines API, which means that should not be used outside of
- * `kotlinx.coroutines`, because their signatures and semantics will be changing between release without any
+ * `kotlinx.coroutines`, because their signatures and semantics will change between future releases without any
  * warnings and without providing any migration aids.
  */
 @Retention(value = AnnotationRetention.BINARY)

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

@@ -51,7 +51,7 @@ public interface CoroutineScope {
     /**
      * The context of this scope.
      * Context is encapsulated by the scope and used for implementation of coroutine builders that are extensions on the scope.
-     * Accessing this property in general code is not recommended for any purposes except accessing [Job] instance for advanced usages.
+     * Accessing this property in general code is not recommended for any purposes except accessing the [Job] instance for advanced usages.
      *
      * By convention, should contain an instance of a [job][Job] to enforce structured concurrency.
      */
@@ -91,7 +91,7 @@ public operator fun CoroutineScope.plus(context: CoroutineContext): CoroutineSco
 public fun MainScope(): CoroutineScope = ContextScope(SupervisorJob() + Dispatchers.Main)
 
 /**
- * Returns `true` when current [Job] is still active (has not completed and was not cancelled yet).
+ * Returns `true` when the current [Job] is still active (has not completed and was not cancelled yet).
  *
  * Check this property in long-running computation loops to support cancellation:
  * ```

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

@@ -13,36 +13,36 @@ public expect object Dispatchers {
     /**
      * The default [CoroutineDispatcher] that is used by all standard builders like
      * [launch][CoroutineScope.launch], [async][CoroutineScope.async], etc
-     * if no dispatcher nor any other [ContinuationInterceptor] is specified in their context.
+     * if neither a dispatcher nor any other [ContinuationInterceptor] is specified in their context.
      *
-     * It is backed by a shared pool of threads on JVM. By default, the maximal number of threads used
-     * by this dispatcher is equal to the number CPU cores, but is at least two.
+     * It is backed by a shared pool of threads on JVM. By default, the maximum number of threads used
+     * by this dispatcher is equal to the number of CPU cores, but is at least two.
      */
     public val Default: CoroutineDispatcher
 
     /**
      * A coroutine dispatcher that is confined to the Main thread operating with UI objects.
-     * Usually such dispatcher is single-threaded.
+     * Usually such dispatchers are single-threaded.
      *
-     * Access to this property may throw [IllegalStateException] if no main dispatchers are present in the classpath.
+     * Access to this property may throw an [IllegalStateException] if no main dispatchers are present in the classpath.
      *
      * Depending on platform and classpath it can be mapped to different dispatchers:
-     * - On JS and Native it is equivalent of [Default] dispatcher.
-     * - On JVM it either Android main thread dispatcher, JavaFx or Swing EDT dispatcher. It is chosen by
+     * - On JS and Native it is equivalent to the [Default] dispatcher.
+     * - On JVM it either the Android main thread dispatcher, JavaFx or Swing EDT dispatcher. It is chosen by the
      *   [`ServiceLoader`](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html).
      *
-     * In order to work with `Main` dispatcher, following artifact should be added to project runtime dependencies:
-     *  - `kotlinx-coroutines-android` for Android Main thread dispatcher
-     *  - `kotlinx-coroutines-javafx` for JavaFx Application thread dispatcher
-     *  - `kotlinx-coroutines-swing` for Swing EDT dispatcher
+     * In order to work with the `Main` dispatcher, the following artifact should be added to the project runtime dependencies:
+     *  - `kotlinx-coroutines-android` — for Android Main thread dispatcher
+     *  - `kotlinx-coroutines-javafx` — for JavaFx Application thread dispatcher
+     *  - `kotlinx-coroutines-swing` — for Swing EDT dispatcher
      *
-     * Implementation note: [MainCoroutineDispatcher.immediate] is not supported on Native and JS platforms.
+     * Implementation note: [MainCoroutineDispatcher.immediate] is not supported on the Native and JS platforms.
      */
     public val Main: MainCoroutineDispatcher
 
     /**
      * A coroutine dispatcher that is not confined to any specific thread.
-     * It executes initial continuation of the coroutine in the current call-frame
+     * It executes the initial continuation of a coroutine in the current call-frame
      * and lets the coroutine resume in whatever thread that is used by the corresponding suspending function, without
      * mandating any specific threading policy. Nested coroutines launched in this dispatcher form an event-loop to avoid
      * stack overflows.
@@ -64,12 +64,12 @@ public expect object Dispatchers {
      * println("Done")
      * ```
      * Can print both "1 2 3" and "1 3 2", this is an implementation detail that can be changed.
-     * But it is guaranteed that "Done" will be printed only when both `withContext` are completed.
+     * But it is guaranteed that "Done" will be printed only when both `withContext` calls are completed.
      *
      * Note that if you need your coroutine to be confined to a particular thread or a thread-pool after resumption,
      * but still want to execute it in the current call-frame until its first suspension, then you can use
      * an optional [CoroutineStart] parameter in coroutine builders like
-     * [launch][CoroutineScope.launch] and [async][CoroutineScope.async] setting it to the
+     * [launch][CoroutineScope.launch] and [async][CoroutineScope.async] setting it to
      * the value of [CoroutineStart.UNDISPATCHED].
      */
     public val Unconfined: CoroutineDispatcher

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

@@ -12,16 +12,16 @@ import kotlin.coroutines.intrinsics.*
 import kotlin.jvm.*
 
 /**
- * Runs a given suspending [block] of code inside a coroutine with a specified timeout and throws
- * [TimeoutCancellationException] if timeout was exceeded.
+ * Runs a given suspending [block] of code inside a coroutine with a specified [timeout][timeMillis] and throws
+ * a [TimeoutCancellationException] if the timeout was exceeded.
  *
  * The code that is executing inside the [block] is cancelled on timeout and the active or next invocation of
- * cancellable suspending function inside the block throws [TimeoutCancellationException].
+ * the cancellable suspending function inside the block throws a [TimeoutCancellationException].
  *
- * The sibling function that does not throw exception on timeout is [withTimeoutOrNull].
- * Note that timeout action can be specified for [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
+ * The sibling function that does not throw an exception on timeout is [withTimeoutOrNull].
+ * Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
  *
- * Implementation note: how exactly time is tracked is an implementation detail of [CoroutineDispatcher] in the context.
+ * Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
  *
  * @param timeMillis timeout time in milliseconds.
  */
@@ -33,16 +33,16 @@ public suspend fun <T> withTimeout(timeMillis: Long, block: suspend CoroutineSco
 }
 
 /**
- * Runs a given suspending block of code inside a coroutine with a specified timeout and returns
+ * Runs a given suspending block of code inside a coroutine with a specified [timeout][timeMillis] and returns
  * `null` if this timeout was exceeded.
  *
  * The code that is executing inside the [block] is cancelled on timeout and the active or next invocation of
- * cancellable suspending function inside the block throws [TimeoutCancellationException].
+ * cancellable suspending function inside the block throws a [TimeoutCancellationException].
  *
- * The sibling function that throws exception on timeout is [withTimeout].
- * Note that timeout action can be specified for [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
+ * The sibling function that throws an exception on timeout is [withTimeout].
+ * Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
  *
- * Implementation note: how exactly time is tracked is an implementation detail of [CoroutineDispatcher] in the context.
+ * Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
  *
  * @param timeMillis timeout time in milliseconds.
  */
@@ -57,7 +57,7 @@ public suspend fun <T> withTimeoutOrNull(timeMillis: Long, block: suspend Corout
             setupTimeout<T?, T?>(timeoutCoroutine, block)
         }
     } catch (e: TimeoutCancellationException) {
-        // Return null iff it's our exception, otherwise propagate it upstream (e.g. in case of nested withTimeouts)
+        // Return null if it's our exception, otherwise propagate it upstream (e.g. in case of nested withTimeouts)
         if (e.coroutine === coroutine) {
             return null
         }
@@ -73,8 +73,8 @@ private fun <U, T: U> setupTimeout(
     val cont = coroutine.uCont
     val context = cont.context
     coroutine.disposeOnCompletion(context.delay.invokeOnTimeout(coroutine.time, coroutine))
-    // restart block using new coroutine with new job,
-    // however start it as undispatched coroutine, because we are already in the proper context
+    // restart the block using a new coroutine with a new job,
+    // however, start it undispatched, because we already are in the proper context
     return coroutine.startUndispatchedOrReturnIgnoreTimeout(coroutine, block)
 }
 
@@ -114,7 +114,7 @@ public class TimeoutCancellationException internal constructor(
     @JvmField internal val coroutine: Job?
 ) : CancellationException(message) {
     /**
-     * Creates timeout exception with a given message.
+     * Creates a timeout exception with the given message.
      * This constructor is needed for exception stack-traces recovery.
      */
     @Suppress("UNUSED")