Improve documentation, make MainScope experimental, cleanup leftovers

Author: qwwdfsad

binary-compatibility-validator/resources/api.properties

@@ -2,7 +2,7 @@
 # Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-module.roots=core integration native reactive ui test
+module.roots=core integration native reactive ui test debug
 module.marker=build.gradle
 module.ignore=kotlinx-coroutines-rx-example stdlib-stubs
 

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

@@ -94,6 +94,7 @@ public operator fun CoroutineScope.plus(context: CoroutineContext): CoroutineSco
  * `val scope = MainScope() + CoroutineName("MyActivity")`.
  */
 @Suppress("FunctionName")
+@ExperimentalCoroutinesApi // Experimental since 1.1.0, tentatively until 1.2.0
 public fun MainScope(): CoroutineScope = ContextScope(SupervisorJob() + Dispatchers.Main)
 
 /**
@@ -137,7 +138,7 @@ public val CoroutineScope.isActive: Boolean
  *
  * ```
  */
-object GlobalScope : CoroutineScope {
+public object GlobalScope : CoroutineScope {
     /**
      * Returns [EmptyCoroutineContext].
      */

core/kotlinx-coroutines-core/resources/META-INF/proguard/coroutines.pro

@@ -1,7 +1,6 @@
 # ServiceLoader support
 -keepnames class kotlinx.coroutines.internal.MainDispatcherFactory {}
 -keepnames class kotlinx.coroutines.CoroutineExceptionHandler {}
--keepnames class kotlinx.coroutines.test.internal.InjectableDispatcherFactory {}
 
 # Most of volatile fields are updated with AFU and should not be mangled
 -keepclassmembernames class kotlinx.** {

core/kotlinx-coroutines-core/src/internal/MainDispatchers.kt

@@ -28,6 +28,8 @@ internal object MainDispatcherLoader {
  * If anything goes wrong while trying to create main dispatcher (class not found,
  * initialization failed, etc), then replace the main dispatcher with a special
  * stub that throws an error message on any attempt to actually use it.
+ *
+ * @suppress internal API
  */
 @InternalCoroutinesApi
 public fun MainDispatcherFactory.tryCreateDispatcher(factories: List<MainDispatcherFactory>): MainCoroutineDispatcher =

core/kotlinx-coroutines-core/src/internal/ProbesSupport.kt

@@ -8,4 +8,4 @@ package kotlinx.coroutines.internal
 import kotlin.coroutines.*
 import kotlin.coroutines.jvm.internal.probeCoroutineCreated as probe
 
-internal actual inline fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T> = probe(completion)
+internal actual inline fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T> = probe(completion)

core/kotlinx-coroutines-debug/README.md

@@ -4,19 +4,28 @@ Debugging facilities for `kotlinx.coroutines` on JVM.
 
 ### Overview
 
-This module provides a debug JVM agent which allows to track and trace existing coroutines.
+This module provides a debug JVM agent that allows to track and trace existing coroutines.
 The main entry point to debug facilities is [DebugProbes] API.
-Call to [DebugProbes.install] installs debug agent via ByteBuddy and starts to spy on coroutines when they are created, suspended or resumed.
+Call to [DebugProbes.install] installs debug agent via ByteBuddy and starts spying on coroutines when they are created, suspended and resumed.
 
 After that, you can use [DebugProbes.dumpCoroutines] to print all active (suspended or running) coroutines, including their state, creation and
 suspension stacktraces.
 Additionally, it is possible to process the list of such coroutines via [DebugProbes.dumpCoroutinesState] or dump isolated parts
-of coroutines hierarchy referenced by a [Job] instance using [DebugProbes.printScope] or [DebugProbes.printJob].
+of coroutines hierarchy referenced by a [Job] or [CoroutineScope] instances using  [DebugProbes.printJob] and [DebugProbes.printScope] respectively.
+
+### Using in your project
+
+Add `kotlinx-coroutines-debug` to your project test dependencies:
+```
+dependencies {
+    testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-debug:1.1.0-alpha'
+}
+```
 
 ### Using as JVM agent
 
 It is possible to use this module as a standalone JVM agent to enable debug probes on the application startup.
-You can run your application with an additional argument: `-javaagent:kotlinx-coroutines-debug-1.0.1.jar`.
+You can run your application with an additional argument: `-javaagent:kotlinx-coroutines-debug-1.1.0-alpha.jar`.
 Additionally, on Linux and Mac OS X you can use `kill -5 $pid` command in order to force your application to print all alive coroutines.
 
 
@@ -110,6 +119,7 @@ Do not use this module in production environment and do not rely on the format o
 <!--- MODULE kotlinx-coroutines-core -->
 <!--- INDEX kotlinx.coroutines -->
 [Job]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html
+[CoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html
 <!--- MODULE kotlinx-coroutines-debug -->
 <!--- INDEX kotlinx.coroutines.debug -->
 [DebugProbes]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/index.html

core/kotlinx-coroutines-test/README.md

@@ -7,7 +7,7 @@ Test utilities for `kotlinx.coroutines`. Provides `Dispatchers.setMain` to overr
 Add `kotlinx-coroutines-test` to your project test dependencies:
 ```
 dependencies {
-    testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.0.1'
+    testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.1.0-alpha'
 }
 ```
 

native/kotlinx-coroutines-core-native/src/internal/ProbesSupport.kt

@@ -7,4 +7,4 @@ package kotlinx.coroutines.internal
 import kotlin.coroutines.*
 
 @Suppress("NOTHING_TO_INLINE")
-internal actual inline fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T> = completion
+internal actual inline fun <T> probeCoroutineCreated(completion: Continuation<T>): Continuation<T> = completion