Improve CoroutineScope documentation: mention job convention, get rid of lateinit example, discourage manual implementation of the scope

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='getting-it-together'></a>[Getting it together](docs/coroutine-context-and-dispatchers.md#getting-it-together)
+  * <a name='coroutine-scope'></a>[Coroutine scope](docs/coroutine-context-and-dispatchers.md#coroutine-scope)
   * <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)
-  * [Getting it together](#getting-it-together)
+  * [Coroutine scope](#coroutine-scope)
   * [Thread-local data](#thread-local-data)
 
 <!--- END_TOC -->
@@ -487,7 +487,7 @@ I'm working in thread DefaultDispatcher-worker-1 @test#2
 
 <!--- TEST FLEXIBLE_THREAD -->
 
-### Getting it together
+### Coroutine scope
 
 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
@@ -516,14 +516,15 @@ class Activity {
 
 </div>
 
-We can implement [CoroutineScope] interface in this `Actvity` class. The best way to do it is
+Alternatively, 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 : CoroutineScope by CoroutineScope(Dispatchers.Default)
+    class Activity : CoroutineScope by CoroutineScope(Dispatchers.Default) {
+    // to be continued ...
 ```
 
 </div>

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

@@ -6,58 +6,54 @@ package kotlinx.coroutines
 
 import kotlinx.coroutines.internal.*
 import kotlinx.coroutines.intrinsics.*
-import kotlin.coroutines.intrinsics.*
 import kotlin.coroutines.*
+import kotlin.coroutines.intrinsics.*
 
 /**
  * Defines a scope for new coroutines. Every coroutine builder
  * is an extension on [CoroutineScope] and inherits its [coroutineContext][CoroutineScope.coroutineContext]
  * 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.
+ *
+ * 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.
+ *
  * Every coroutine builder (like [launch][CoroutineScope.launch], [async][CoroutineScope.async], etc)
  * and every scoping function (like [coroutineScope], [withContext], etc) provides _its own_ scope
  * with its own [Job] instance into the inner block of code it runs.
- * By convention, they all wait for all the coroutines inside
- * their block to complete before completing themselves, thus enforcing the
- * discipline of **structured concurrency**.
+ * By convention, they all wait for all the coroutines inside their block to complete before completing themselves,
+ * thus enforcing the discipline of **structured concurrency**.
  *
- * [CoroutineScope] should be implemented on entities with well-defined lifecycle that are responsible
+ * [CoroutineScope] should be implemented (or used as a field) on entities with a well-defined lifecycle that are responsible
  * for launching children coroutines. Example of such entity on Android is Activity.
  * Usage of this interface may look like this:
  *
  * ```
- * class MyActivity : AppCompatActivity(), CoroutineScope {
- *     lateinit var job: Job
- *     override val coroutineContext: CoroutineContext
- *         get() = Dispatchers.Main + job
- *
- *     override fun onCreate(savedInstanceState: Bundle?) {
- *         super.onCreate(savedInstanceState)
- *         job = Job()
- *     }
- *
+ * class MyActivity : AppCompatActivity(), CoroutineScope by MainScope() {
  *     override fun onDestroy() {
- *         super.onDestroy()
- *         job.cancel() // Cancel job on activity destroy. After destroy all children jobs will be cancelled automatically
+ *         cancel() // cancel is extension on CoroutineScope
  *     }
  *
  *     /*
  *      * Note how coroutine builders are scoped: if activity is destroyed or any of the launched coroutines
  *      * in this method throws an exception, then all nested coroutines are cancelled.
  *      */
  *     fun showSomeData() = launch { // <- extension on current activity, launched in the main thread
- *        val data = withContext(Dispatchers.IO) {
- *            // Provides withContext scope that is child of he outer launch scope
- *            // blocking I/O operation
- *        }
+ *        // ... here we can use suspending functions or coroutine builders with other dispatchers
  *        draw(data) // draw in the main thread
  *     }
  * }
  * ```
  */
 public interface CoroutineScope {
     /**
-     * Context of this scope.
+     * 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.
+     *
+     * By convention, should contain an instance of a [job][Job] to enforce structured concurrency.
      */
     public val coroutineContext: CoroutineContext
 }