Update debug module documentation

Author: qwwdfsad

README.md

@@ -39,6 +39,7 @@ GlobalScope.launch {
   * `Dispatchers.setMain` to override `Dispatchers.Main` in tests.
 * [debug](kotlinx-coroutines-debug/README.md) — debug utilities for coroutines.
   * `DebugProbes` API to probe, keep track of, print and dump active coroutines.
+  * `CoroutinesTimeout` test rule to automatically dump coroutines on test timeout.
 * [reactive](reactive/README.md) — modules that provide builders and iteration support for various reactive streams libraries:
   * Reactive Streams, RxJava 2.x, and Project Reactor. 
 * [ui](ui/README.md) — modules that provide coroutine dispatchers for various single-threaded UI libraries:

kotlinx-coroutines-core/jvm/test/guide/example-compose-05.kt

@@ -9,18 +9,18 @@ import kotlinx.coroutines.*
 import kotlin.system.*
 
 fun main() = runBlocking<Unit> {
-//sampleStart
+    //sampleStart
     val time = measureTimeMillis {
         println("The answer is ${concurrentSum()}")
     }
     println("Completed in $time ms")
-//sampleEnd    
+    //sampleEnd    
 }
 
 suspend fun concurrentSum(): Int = coroutineScope {
     val one = async { doSomethingUsefulOne() }
     val two = async { doSomethingUsefulTwo() }
-     one.await() + two.await()
+    one.await() + two.await()
 }
 
 suspend fun doSomethingUsefulOne(): Int {

kotlinx-coroutines-core/jvm/test/guide/example-compose-06.kt

@@ -28,5 +28,5 @@ suspend fun failedConcurrentSum(): Int = coroutineScope {
         println("Second child throws an exception")
         throw ArithmeticException()
     }
-        one.await() + two.await()
+    one.await() + two.await()
 }

kotlinx-coroutines-debug/README.md

@@ -22,6 +22,43 @@ dependencies {
 }
 ```
 
+### Using in unit tests
+
+For JUnit4 debug module provides special test rule, [CoroutinesTimeout], for installing debug probes
+and dump coroutines on timeout to simplify tests debugging.
+
+Its usage is better to demonstrate by the example (runnable code is [here](test/TestRuleExample.kt)):
+ 
+```kotlin
+class TestRuleExample {
+    @Rule
+    @JvmField
+    public val timeout = CoroutinesTimeout.seconds(1)
+
+    private suspend fun someFunctionDeepInTheStack() {
+        withContext(Dispatchers.IO) {
+            delay(Long.MAX_VALUE)
+            println("This line is never executed")
+        }
+
+        println("This line is never executed as well")
+    }
+
+    @Test
+    fun hangingTest() = runBlocking {
+        val job = launch {
+            someFunctionDeepInTheStack()
+        }
+
+        println("Doing some work...")
+        job.join()
+    }
+}
+```
+
+After 1 second, test will fail with `TestTimeoutException` and all coroutines (`runBlocking` and `launch`) and their
+stacktraces will be dumped to the console.
+
 ### Using as JVM agent
 
 It is possible to use this module as a standalone JVM agent to enable debug probes on the application startup.
@@ -112,4 +149,6 @@ Do not use this module in production environment and do not rely on the format o
 [DebugProbes.dumpCoroutinesState]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/dump-coroutines-state.html
 [DebugProbes.printJob]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/print-job.html
 [DebugProbes.printScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/print-scope.html
+<!--- INDEX kotlinx.coroutines.debug.junit4 -->
+[CoroutinesTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug.junit4/-coroutines-timeout/index.html
 <!--- END -->

kotlinx-coroutines-debug/test/TestRuleExample.kt

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.debug.junit4.*
+import org.junit.*
+
+@Ignore // do not run it on CI
+class TestRuleExample {
+
+    @JvmField
+    @Rule
+    public val timeout = CoroutinesTimeout.seconds(1)
+
+    private suspend fun someFunctionDeepInTheStack() {
+        withContext(Dispatchers.IO) {
+            delay(Long.MAX_VALUE)
+            println("This line is never executed")
+        }
+
+        println("This line is never executed as well")
+    }
+
+    @Test
+    fun hangingTest() = runBlocking {
+        val job = launch {
+            someFunctionDeepInTheStack()
+        }
+
+        println("Doing some work...")
+        job.join()
+    }
+
+    @Test
+    fun successfulTest() = runBlocking {
+        launch {
+            delay(10)
+        }.join()
+    }
+
+}