Improve docs for the test module (#3074)

Fixes #3067
Fixes #3061

Author: dkhalanskyjb

kotlinx-coroutines-test/common/src/TestScope.kt

@@ -75,7 +75,7 @@ public fun TestScope.runCurrent(): Unit = testScheduler.runCurrent()
  * Moves the virtual clock of this dispatcher forward by [the specified amount][delayTimeMillis], running the
  * scheduled tasks in the meantime.
  *
- * In contrast with [TestScope.advanceTimeBy], this function does not run the tasks scheduled at the moment
+ * In contrast with `TestCoroutineScope.advanceTimeBy`, this function does not run the tasks scheduled at the moment
  * [currentTime] + [delayTimeMillis].
  *
  * @throws IllegalStateException if passed a negative [delay][delayTimeMillis].

kotlinx-coroutines-test/jvm/src/migration/DelayController.kt

@@ -11,6 +11,12 @@ import kotlinx.coroutines.*
  * Control the virtual clock time of a [CoroutineDispatcher].
  *
  * Testing libraries may expose this interface to the tests instead of [TestCoroutineDispatcher].
+ *
+ * This interface is deprecated without replacement.
+ * Instead, [TestCoroutineScheduler] is supposed to be used to control the virtual time.
+ * Please see the
+ * [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
+ * for an instruction on how to update the code for the new API.
  */
 @ExperimentalCoroutinesApi
 @Deprecated(

kotlinx-coroutines-test/jvm/src/migration/TestBuildersDeprecated.kt

@@ -14,6 +14,10 @@ import kotlin.jvm.*
 /**
  * Executes a [testBody] inside an immediate execution dispatcher.
  *
+ * This method is deprecated in favor of [runTest]. Please see the
+ * [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
+ * for an instruction on how to update the code for the new API.
+ *
  * This is similar to [runBlocking] but it will immediately progress past delays and into [launch] and [async] blocks.
  * You can use this to write tests that execute in the presence of calls to [delay] without causing your test to take
  * extra time.
@@ -45,7 +49,10 @@ import kotlin.jvm.*
  *        then they must implement [DelayController] and [TestCoroutineExceptionHandler] respectively.
  * @param testBody The code of the unit-test.
  */
-@Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.WARNING)
+@Deprecated("Use `runTest` instead to support completing from other dispatchers. " +
+    "Please see the migration guide for details: " +
+    "https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md",
+    level = DeprecationLevel.WARNING)
 // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun runBlockingTest(
     context: CoroutineContext = EmptyCoroutineContext,
@@ -101,8 +108,16 @@ public fun runBlockingTestOnTestScope(
 
 /**
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineScope].
+ *
+ * This method is deprecated in favor of [runTest], whereas [TestCoroutineScope] is deprecated in favor of [TestScope].
+ * Please see the
+ * [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
+ * for an instruction on how to update the code for the new API.
  */
-@Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.WARNING)
+@Deprecated("Use `runTest` instead to support completing from other dispatchers. " +
+    "Please see the migration guide for details: " +
+    "https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md",
+    level = DeprecationLevel.WARNING)
 // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun TestCoroutineScope.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit): Unit =
     runBlockingTest(coroutineContext, block)
@@ -117,8 +132,16 @@ public fun TestScope.runBlockingTest(block: suspend TestScope.() -> Unit): Unit
 
 /**
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineDispatcher].
+ *
+ * This method is deprecated in favor of [runTest], whereas [TestCoroutineScope] is deprecated in favor of [TestScope].
+ * Please see the
+ * [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
+ * for an instruction on how to update the code for the new API.
  */
-@Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.WARNING)
+@Deprecated("Use `runTest` instead to support completing from other dispatchers. " +
+    "Please see the migration guide for details: " +
+    "https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md",
+    level = DeprecationLevel.WARNING)
 // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun TestCoroutineDispatcher.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit): Unit =
     runBlockingTest(this, block)

kotlinx-coroutines-test/jvm/src/migration/TestCoroutineScope.kt

@@ -11,9 +11,17 @@ import kotlin.coroutines.*
 
 /**
  * A scope which provides detailed control over the execution of coroutines for tests.
+ *
+ * This scope is deprecated in favor of [TestScope].
+ * Please see the
+ * [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
+ * for an instruction on how to update the code for the new API.
  */
 @ExperimentalCoroutinesApi
-@Deprecated("Use `TestScope` in combination with `runTest` instead")
+@Deprecated("Use `TestScope` in combination with `runTest` instead." +
+    "Please see the migration guide for details: " +
+    "https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md",
+    level = DeprecationLevel.WARNING)
 // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public interface TestCoroutineScope : CoroutineScope {
     /**
@@ -139,6 +147,11 @@ public fun TestCoroutineScope(context: CoroutineContext = EmptyCoroutineContext)
 /**
  * A coroutine scope for launching test coroutines.
  *
+ * This is a function for aiding in migration from [TestCoroutineScope] to [TestScope].
+ * Please see the
+ * [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
+ * for an instruction on how to update the code for the new API.
+ *
  * It ensures that all the test module machinery is properly initialized.
  * * If [context] doesn't define a [TestCoroutineScheduler] for orchestrating the virtual time used for delay-skipping,
  *   a new one is created, unless either