Update cancellation guide: get rid of explicit Job in general code, promote usage of coroutine scope get rid of counter-intuitive lateinit and getters in coroutine context

Author: qwwdfsad

coroutines-guide.md

@@ -38,7 +38,7 @@ The main coroutines guide has moved to the [docs folder](docs/coroutines-guide.m
   * <a name='parental-responsibilities'></a>[Parental responsibilities](docs/coroutine-context-and-dispatchers.md#parental-responsibilities)
   * <a name='naming-coroutines-for-debugging'></a>[Naming coroutines for debugging](docs/coroutine-context-and-dispatchers.md#naming-coroutines-for-debugging)
   * <a name='combining-context-elements'></a>[Combining context elements](docs/coroutine-context-and-dispatchers.md#combining-context-elements)
-  * <a name='cancellation-via-explicit-job'></a>[Cancellation via explicit job](docs/coroutine-context-and-dispatchers.md#cancellation-via-explicit-job)
+  * <a name='getting-it-together'></a>[Getting it together](docs/coroutine-context-and-dispatchers.md#getting-it-together)
   * <a name='thread-local-data'></a>[Thread-local data](docs/coroutine-context-and-dispatchers.md#thread-local-data)
 <!--- TOC_REF docs/exception-handling.md -->
 * <a name='exception-handling'></a>[Exception handling](docs/exception-handling.md#exception-handling)

docs/coroutine-context-and-dispatchers.md

@@ -30,7 +30,7 @@ class DispatchersGuideTest {
   * [Parental responsibilities](#parental-responsibilities)
   * [Naming coroutines for debugging](#naming-coroutines-for-debugging)
   * [Combining context elements](#combining-context-elements)
-  * [Cancellation via explicit job](#cancellation-via-explicit-job)
+  * [Getting it together](#getting-it-together)
   * [Thread-local data](#thread-local-data)
 
 <!--- END_TOC -->
@@ -487,48 +487,43 @@ I'm working in thread DefaultDispatcher-worker-1 @test#2
 
 <!--- TEST FLEXIBLE_THREAD -->
 
-### Cancellation via explicit job
+### Getting it together
 
 Let us put our knowledge about contexts, children and jobs together. Assume that our application has
 an object with a lifecycle, but that object is not a coroutine. For example, we are writing an Android application
 and launch various coroutines in the context of an Android activity to perform asynchronous operations to fetch 
 and update data, do animations, etc. All of these coroutines must be cancelled when activity is destroyed
-to avoid memory leaks. 
-  
-We manage a lifecycle of our coroutines by creating an instance of [Job] that is tied to 
-the lifecycle of our activity. A job instance is created using [Job()] factory function when
-activity is created and it is cancelled when an activity is destroyed like this:
+to avoid memory leaks. We, of course, can manipulate contexts and jobs manually to tie activity's 
+and coroutines lifecycles, but `kotlinx.coroutines` provides an abstraction that encapsulates that: [CoroutineScope].
+You should be already familiar with coroutine scope as all coroutine builders are declared as extensions on it. 
 
+We manage a lifecycle of our coroutines by creating an instance of [CoroutineScope] that is tied to 
+the lifecycle of our activity. `CoroutineScope` instance can be created by [CoroutineScope()] or [MainScope()]
+factory functions. The former creates a general-purpose scope, while the latter creates scope for UI applications and uses
+[Dispatchers.Main] as default dispatcher:
 
 <div class="sample" markdown="1" theme="idea" data-highlight-only>
 
 ```kotlin
-class Activity : CoroutineScope {
-    lateinit var job: Job
-
-    fun create() {
-        job = Job()
-    }
-
+class Activity {
+    private val mainScope = MainScope()
+    
     fun destroy() {
-        job.cancel()
+        mainScope.cancel()
     }
     // to be continued ...
 ```
 
 </div>
 
-We also implement [CoroutineScope] interface in this `Actvity` class. We only need to provide an override
-for its [CoroutineScope.coroutineContext] property to specify the context for coroutines launched in its
-scope. We combine the desired dispatcher (we used [Dispatchers.Default] in this example) and a job:
+We can implement [CoroutineScope] interface in this `Actvity` class. The best way to do it is
+to use delegation with default factory functions.
+We also can combine the desired dispatcher (we used [Dispatchers.Default] in this example) with the scope:
 
 <div class="sample" markdown="1" theme="idea" data-highlight-only>
 
 ```kotlin
-    // class Activity continues
-    override val coroutineContext: CoroutineContext
-        get() = Dispatchers.Default + job
-    // to be continued ...
+    class Activity : CoroutineScope by CoroutineScope(Dispatchers.Default)
 ```
 
 </div>
@@ -566,23 +561,13 @@ onto the screen anymore if we wait:
 import kotlin.coroutines.*
 import kotlinx.coroutines.*
 
-class Activity : CoroutineScope {
-    lateinit var job: Job
-
-    fun create() {
-        job = Job()
-    }
+class Activity : CoroutineScope by CoroutineScope(Dispatchers.Default) {
 
     fun destroy() {
-        job.cancel()
+        cancel() // Extension on CoroutineScope
     }
     // to be continued ...
 
-    // class Activity continues
-    override val coroutineContext: CoroutineContext
-        get() = Dispatchers.Default + job
-    // to be continued ...
-
     // class Activity continues
     fun doSomething() {
         // launch ten coroutines for a demo, each working for a different time
@@ -598,7 +583,6 @@ class Activity : CoroutineScope {
 fun main() = runBlocking<Unit> {
 //sampleStart
     val activity = Activity()
-    activity.create() // create an activity
     activity.doSomething() // run test function
     println("Launched coroutines")
     delay(500L) // delay for half a second
@@ -712,7 +696,9 @@ that should be implemented.
 [CoroutineScope.coroutineContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/coroutine-context.html
 [Job.join]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/join.html
 [CoroutineName]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-name/index.html
-[Job()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job.html
+[CoroutineScope()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope.html
+[MainScope()]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-main-scope.html
+[Dispatchers.Main]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-main.html
 [asContextElement]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/java.lang.-thread-local/as-context-element.html
 [ThreadContextElement]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-thread-context-element/index.html
 <!--- END -->

kotlinx-coroutines-core/jvm/test/guide/example-context-10.kt

@@ -8,23 +8,13 @@ package kotlinx.coroutines.guide.context10
 import kotlin.coroutines.*
 import kotlinx.coroutines.*
 
-class Activity : CoroutineScope {
-    lateinit var job: Job
-
-    fun create() {
-        job = Job()
-    }
+class Activity : CoroutineScope by CoroutineScope(Dispatchers.Default) {
 
     fun destroy() {
-        job.cancel()
+        cancel() // Extension on CoroutineScope
     }
     // to be continued ...
 
-    // class Activity continues
-    override val coroutineContext: CoroutineContext
-        get() = Dispatchers.Default + job
-    // to be continued ...
-
     // class Activity continues
     fun doSomething() {
         // launch ten coroutines for a demo, each working for a different time
@@ -40,7 +30,6 @@ class Activity : CoroutineScope {
 fun main() = runBlocking<Unit> {
 //sampleStart
     val activity = Activity()
-    activity.create() // create an activity
     activity.doSomething() // run test function
     println("Launched coroutines")
     delay(500L) // delay for half a second