Small edits & updates in the text of coroutines hands-on

Author: svtk

Introduction to Coroutines and Channels/01_Introduction.md

@@ -25,11 +25,10 @@ by Roman Elizarov at KotlinConf.
 
 ### Set-up
 
-We'll need one of the latest versions of IntelliJ IDEA, so any version from 2018.1 onwards.
-You can download the latest free community version [here](https://www.jetbrains.com/idea/download/).
+We'll need IntelliJ IDEA; you can download the latest free community version [here](https://www.jetbrains.com/idea/download/).
 
-Make sure version 1.3 of the Kotlin plugin is installed.
-To update the Kotlin plugin, use `Tools | Kotlin | Configure 
Kotlin Plugin Updates`.
+Make sure version 1.4 of the Kotlin plugin is installed.
+To update the Kotlin plugin, use `Tools | Kotlin | Configure Kotlin Plugin Updates`.
 
 ### Downloading project
 
@@ -43,13 +42,9 @@ and specifying the project path:
 $ git clone http://github.com/kotlin-hands-on/intro-coroutines
 ```
 
-Note that the project includes the `solutions` branch, so it is possible to use the `Compare with branch...`
+The project includes the `solutions` branch, so it is possible to use the `Compare with branch...`
 action to compare your solution with the proposed one.
 
-Alternatively, you can [download the project](http://github.com/kotlin-hands-on/intro-coroutines/archive/master.zip) directly
-(but only the `main` branch).
-
-
 ### Generating GitHub developer token
 
 We'll be using GitHub API.

Introduction to Coroutines and Channels/02_BlockingRequest.md

@@ -116,8 +116,9 @@ The resulting list should be sorted in descending order according to the number
 #### Task
 
 Open `src/tasks/Aggregation.kt` and implement `List<User>.aggregate()` function.
-[The corresponding test file](https://www.jetbrains.com/help/idea/navigating-between-test-and-test-subject.html)
-shows an example of the expected result.
+The corresponding test file `test/tasks/AggregationKtTest.kt` shows an example of the expected result.
+You can jump between the source code and the test class automatically [using IntelliJ IDEA
+shortcut](https://www.jetbrains.com/help/idea/create-tests.html#test-code-navigation).
 
 After implementing this task, the resulting list for `Kotlin` organization should be similar to the following:
 

Introduction to Coroutines and Channels/04_Suspend.md

@@ -1,6 +1,6 @@
 # Using suspend functions
 
-Retrofit recently added native support for coroutines, and we're going to use it.
+Retrofit provides native support for coroutines, and we're going to use it.
 Instead of returning `Call<List<Repo>>`, we now define our API call as a `suspend` function:
 
 ```kotlin
@@ -15,9 +15,6 @@ interface GitHubService {
 The main idea behind it is that when we use a `suspend` function to perform a request, the underlying thread isn't blocked.
 We'll discuss how exactly it works a bit later. 
 
-To make use of this functionality, we need the latest version of the Retrofit library.
-For this tutorial, we don't need to change anything; the right version is already specified in the project dependencies. 
-
 Note that now `getOrgRepos` returns the result directly instead of returning a `Call`.
 If the result is unsuccessful, an exception is thrown.
 
@@ -46,12 +43,12 @@ interface GitHubService {
 
 The task is to change the code of the function loading contributors to make use of these new `suspend` functions.
 
-However, a `suspend` function can't be called everywhere,
+A `suspend` function can't be called everywhere,
 if it is called from `loadContributorsBlocking`, there will be an error:
 "Suspend function 'getOrgRepos' should only be called from a coroutine or another suspend function".
 So, we need to mark our new version of the `loadContributors` function as `suspend` in order to use this new API.
 
-Please now do the following task, and right after that we'll discuss how `suspend` functions actually work and how
+Please now do the following task, and right after that we'll discuss how `suspend` functions work and how
 they are different from regular ones.
 We'll also see how to call a `suspend` function from a non-suspending one.
 
@@ -92,19 +89,19 @@ directly.
 But that's an implementation detail specific to the Retrofit library.
 With other libraries, the API will be different, but the concept is the same:
 
-_Our code with `suspend` functions looks surprisingly similar to the "blocking" version.
-It's readable and expresses exactly what we're trying to achieve._
+Our code with `suspend` functions looks surprisingly similar to the "blocking" version.
+It's readable and expresses exactly what we're trying to achieve.
 
 The major difference with a blocking version is that instead of blocking the thread, we suspend the coroutine:
 
 ```
-thread -> coroutine
 block -> suspend
+thread -> coroutine
 ```
 
 Coroutines are often called light-weight threads.
 That means we can run code on coroutines similar to how we run code on threads.
-However, the operations that were blocking before (and had to be avoided because of that),
+The operations that were blocking before (and had to be avoided because of that),
 can now suspend the coroutine instead.
 
 How can we start a new coroutine?
@@ -129,7 +126,7 @@ so, we'll simply say that in this case, `launch` _starts a new coroutine_ that i
 for loading data and showing the results.
 
 Coroutines are computations that run on top of threads and can be suspended.
-By saying "suspended", we mean that the corresponding computation can be paused,
+When a coroutine is "suspended", the corresponding computation is paused,
 removed from the thread, and stored in memory.
 Meanwhile, the thread is free to be occupied with other activities:
 
@@ -170,7 +167,7 @@ We can also modify the template for running all the Kotlin files and enable this
 In our case, all the code runs on one coroutine,
 the mentioned above "load contributors" coroutine, denoted as `@coroutine#1`.
 
-However, in this version, while waiting for the result, we don't reuse the thread for sending other requests,
+In this version, while waiting for the result, we don't reuse the thread for sending other requests,
 because we have written our code in a sequential way. The new request is sent only when the previous result is received.
 `suspend` functions treat the thread fairly and don't block it for "waiting",
 but it doesn't yet bring any concurrency to the picture. Let's see how this can be improved.

Introduction to Coroutines and Channels/05_Concurrency.md

@@ -3,7 +3,7 @@
 Kotlin coroutines are extremely inexpensive in comparison to threads.
 Each time when we want to start a new computation asynchronously, we can create a new coroutine.
 
-To start a new coroutine we can just use one of the main "coroutine builders": `launch`, `async`, or `runBlocking`.
+To start a new coroutine we use one of the main "coroutine builders": `launch`, `async`, or `runBlocking`.
 Different libraries can define additional coroutine builders.
 
 `async` starts a new coroutine and returns a `Deferred` object.

Introduction to Coroutines and Channels/06_StructuredConcurrency.md

@@ -3,7 +3,7 @@
 _Coroutine scope_ is responsible for the structure and parent-child relationships between different coroutines.
 We always start new coroutines inside a scope.
 _Coroutine context_ stores additional technical information used to run a given coroutine,
-like the dispatcher specifying the thread or threads the coroutine should be scheduled on.
+like the coroutine custom name, or the dispatcher specifying the threads the coroutine should be scheduled on.
 
 When `launch`, `async`, or `runBlocking` are used to start a new coroutine, they automatically create the corresponding scope.
 All these functions take a lambda with receiver as an argument, and the implicit receiver type is the `CoroutineScope`:

Introduction to Coroutines and Channels/07_Progress.md

@@ -4,7 +4,7 @@ Despite the information for some repositories being loaded rather fast,
 the user only sees the resulting list once all the data is loaded.
 Until then, the loader icon runs showing the progress, but there's no information about the current state,
 and what contributors are already loaded.  
-However, we could show the intermediate results earlier and display all the contributors after loading the data
+We could show the intermediate results earlier and display all the contributors after loading the data
 for each of the repositories:
 
 ![](./assets/7-progress/Loading.gif)
@@ -35,10 +35,10 @@ launch(Dispatchers.Default) {
 }
 ```
 
-Note that the `updateResults` parameter is declared as `suspend` in `loadContributorsProgress`.
+The `updateResults` parameter is declared as `suspend` in `loadContributorsProgress`.
 We need that to call `withContext`, which is a `suspend` function inside the corresponding lambda argument.
 
-Note also that `updateResults` callback now takes an additional `Boolean` parameter as an argument saying whether 
+`updateResults` callback takes an additional `Boolean` parameter as an argument saying whether 
 all the loading completed and our results are final.
 
 #### Task
@@ -86,7 +86,7 @@ An `updateResults` callback is called after each request is completed:
 
 We haven't used any concurrency so far. This code is sequential, so we don't need synchronization.
 
-However, we'd like to send requests concurrently and update the intermediate results after getting the response
+We'd like to send requests concurrently and update the intermediate results after getting the response
 for each repository:
 
 ![](./assets/7-progress/ProgressAndConcurrency.png) 

Introduction to Coroutines and Channels/08_Channels.md

@@ -176,7 +176,7 @@ Since we call the `receive` calls sequentially, no additional synchronization is
 As with the `loadContributorsProgress` function, we can create an `allUsers` variable to store
 the intermediate states of the "all contributors" list.
 When we receive each new list from the channel,
-we can add it to the list of all users, aggregate the result, and update the state using the `updateResults` callback:
+we add it to the list of all users, aggregate the result, and update the state using the `updateResults` callback:
 
 ```kotlin
 suspend fun loadContributorsChannels(
@@ -218,6 +218,6 @@ We've learned how to use suspend functions, execute coroutines concurrently, and
 information between coroutines using channels.
 
 Note that neither coroutines nor channels will completely eradicate the complexity that comes from concurrency,
-but they will definitely make your life easier when we need to reason it and understand what's going on.
+but they will definitely make your life easier when you need to reason it and understand what's going on.
 
 Next, we'll discuss how to test the code that uses coroutines.

Introduction to Coroutines and Channels/09_Testing.md

@@ -1,7 +1,7 @@
 # Testing coroutines
 
 Let's discuss how to test the code that uses coroutines.
-It'd be nice to test our solutions and make sure that the solution with concurrent coroutines is faster than the solution
+It'd be nice to test our solutions, make sure that the solution with concurrent coroutines is faster than the solution
 with `suspend` functions, and check that the solution with channels is faster than the simple "progress" one.
 Let's have a look at how to compare the total running time of these solutions.
 
@@ -90,7 +90,7 @@ while virtual time equals the delay argument exactly, which is 1000 milliseconds
 To enjoy the full effect of "virtual" `delay` in child coroutines,
 we should start all the child coroutines with `TestCoroutineDispatcher`. 
 Otherwise, it won't work.
-This dispatcher is automatically inherited from the other `TestCoroutineScope`, unless we provide the same dispatchers:
+This dispatcher is automatically inherited from the other `TestCoroutineScope`, unless we provide a different dispatcher:
 
 ```kotlin
 @Test
@@ -123,7 +123,7 @@ which is more flexible and easier to test.
 Note that the testing API that supports virtual time is experimental and may change in the future.
 By default, we'll see compiler warnings if we use it. 
 To suppress these warnings, we need to annotate the test function or the whole class containing the tests.
-We can add `@UseExperimental(ExperimentalCoroutinesApi::class)` to our test class or function.
+We can add `@OptIn(ExperimentalCoroutinesApi::class)` to our test class or function.
 By adding such annotation, we emphasize that we understand that the API can change and is ready
 to update our usages if needed (most probably, automatically).
 
@@ -211,7 +211,7 @@ The first intermediate result for the last version with 'channels' is available
 and we can see that difference in tests using virtual time.
 
 The tests for the remaining "suspend" and "progress" tasks are very similar;
-we can find them in the project 'solutions' branch.
+you can find them in the project 'solutions' branch.
 
 You can find more information about using virtual time and
 experimental testing package [here](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-test/).