Add deprecation notices

Author: dkhalanskyjb

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

@@ -17,6 +17,7 @@ import kotlinx.coroutines.*
     "Use `TestCoroutineScheduler` to control virtual time.",
     level = DeprecationLevel.WARNING
 )
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public interface DelayController {
     /**
      * Returns the current virtual clock-time as it is known to this Dispatcher.
@@ -106,6 +107,7 @@ public interface DelayController {
         "Please use a dispatcher that is paused by default, like `StandardTestDispatcher`.",
         level = DeprecationLevel.WARNING
     )
+    // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
     public suspend fun pauseDispatcher(block: suspend () -> Unit)
 
     /**
@@ -118,6 +120,7 @@ public interface DelayController {
         "Please use a dispatcher that is paused by default, like `StandardTestDispatcher`.",
         level = DeprecationLevel.WARNING
     )
+    // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
     public fun pauseDispatcher()
 
     /**
@@ -131,6 +134,7 @@ public interface DelayController {
         "Please use a dispatcher that is paused by default, like `StandardTestDispatcher`.",
         level = DeprecationLevel.WARNING
     )
+    // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
     public fun resumeDispatcher()
 }
 
@@ -143,6 +147,7 @@ internal interface SchedulerAsDelayController : DelayController {
         ReplaceWith("this.scheduler.currentTime"),
         level = DeprecationLevel.WARNING
     )
+    // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
     override val currentTime: Long
         get() = scheduler.currentTime
 
@@ -153,6 +158,7 @@ internal interface SchedulerAsDelayController : DelayController {
         ReplaceWith("this.scheduler.apply { advanceTimeBy(delayTimeMillis); runCurrent() }"),
         level = DeprecationLevel.WARNING
     )
+    // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
     override fun advanceTimeBy(delayTimeMillis: Long): Long {
         val oldTime = scheduler.currentTime
         scheduler.advanceTimeBy(delayTimeMillis)
@@ -166,6 +172,7 @@ internal interface SchedulerAsDelayController : DelayController {
         ReplaceWith("this.scheduler.advanceUntilIdle()"),
         level = DeprecationLevel.WARNING
     )
+    // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
     override fun advanceUntilIdle(): Long {
         val oldTime = scheduler.currentTime
         scheduler.advanceUntilIdle()
@@ -178,6 +185,7 @@ internal interface SchedulerAsDelayController : DelayController {
         ReplaceWith("this.scheduler.runCurrent()"),
         level = DeprecationLevel.WARNING
     )
+    // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
     override fun runCurrent(): Unit = scheduler.runCurrent()
 
     /** @suppress */

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

@@ -47,6 +47,7 @@ import kotlin.jvm.*
  * @param testBody The code of the unit-test.
  */
 @Deprecated("Use `runTest` instead to support completing from other dispatchers.", 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,
     testBody: suspend TestCoroutineScope.() -> Unit
@@ -67,6 +68,7 @@ public fun runBlockingTest(
  * A version of [runBlockingTest] that works with [TestScope].
  */
 @Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.WARNING)
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun runBlockingTestOnTestScope(
     context: CoroutineContext = EmptyCoroutineContext,
     testBody: suspend TestScope.() -> Unit
@@ -92,20 +94,23 @@ public fun runBlockingTestOnTestScope(
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineScope].
  */
 @Deprecated("Use `runTest` instead to support completing from other dispatchers.", 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)
 
 /**
  * Convenience method for calling [runBlockingTestOnTestScope] on an existing [TestScope].
  */
 @Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.WARNING)
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun TestScope.runBlockingTest(block: suspend TestScope.() -> Unit): Unit =
     runBlockingTestOnTestScope(coroutineContext, block)
 
 /**
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineDispatcher].
  */
 @Deprecated("Use `runTest` instead to support completing from other dispatchers.", 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)
 
@@ -114,6 +119,7 @@ public fun TestCoroutineDispatcher.runBlockingTest(block: suspend TestCoroutineS
  */
 @ExperimentalCoroutinesApi
 @Deprecated("Use `runTest` instead.", level = DeprecationLevel.WARNING)
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun runTestWithLegacyScope(
     context: CoroutineContext = EmptyCoroutineContext,
     dispatchTimeoutMs: Long = DEFAULT_DISPATCH_TIMEOUT_MS,
@@ -147,6 +153,7 @@ public fun runTestWithLegacyScope(
  */
 @ExperimentalCoroutinesApi
 @Deprecated("Use `TestScope.runTest` instead.", level = DeprecationLevel.WARNING)
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun TestCoroutineScope.runTest(
     dispatchTimeoutMs: Long = DEFAULT_DISPATCH_TIMEOUT_MS,
     block: suspend TestCoroutineScope.() -> Unit

kotlinx-coroutines-test/common/src/migration/TestCoroutineDispatcher.kt

@@ -24,6 +24,7 @@ import kotlin.coroutines.*
 @Deprecated("The execution order of `TestCoroutineDispatcher` can be confusing, and the mechanism of " +
     "pausing is typically misunderstood. Please use `StandardTestDispatcher` or `UnconfinedTestDispatcher` instead.",
     level = DeprecationLevel.WARNING)
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public class TestCoroutineDispatcher(public override val scheduler: TestCoroutineScheduler = TestCoroutineScheduler()):
     TestDispatcher(), Delay, SchedulerAsDelayController
 {

kotlinx-coroutines-test/common/src/migration/TestCoroutineExceptionHandler.kt

@@ -18,6 +18,7 @@ import kotlin.coroutines.*
         "please report your use case at https://github.com/Kotlin/kotlinx.coroutines/issues.",
     level = DeprecationLevel.WARNING
 )
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public interface UncaughtExceptionCaptor {
     /**
      * List of uncaught coroutine exceptions.
@@ -46,6 +47,7 @@ public interface UncaughtExceptionCaptor {
         "It may be to define one's own `CoroutineExceptionHandler` if you just need to handle '" +
         "uncaught exceptions without a special `TestCoroutineScope` integration.", level = DeprecationLevel.WARNING
 )
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public class TestCoroutineExceptionHandler :
     AbstractCoroutineContextElement(CoroutineExceptionHandler), CoroutineExceptionHandler, UncaughtExceptionCaptor {
     private val _exceptions = mutableListOf<Throwable>()

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

@@ -14,6 +14,7 @@ import kotlin.coroutines.*
  */
 @ExperimentalCoroutinesApi
 @Deprecated("Use `TestScope` in combination with `runTest` instead")
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public sealed interface TestCoroutineScope : CoroutineScope {
     /**
      * Called after the test completes.
@@ -35,6 +36,8 @@ public sealed interface TestCoroutineScope : CoroutineScope {
      * @throws IllegalStateException if called more than once.
      */
     @ExperimentalCoroutinesApi
+    @Deprecated("Please call `runTest`, which automatically performs the cleanup, instead of using this function.")
+    // Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
     public fun cleanupTestCoroutines()
 
     /**
@@ -127,6 +130,7 @@ internal fun CoroutineContext.activeJobs(): Set<Job> {
     ),
     level = DeprecationLevel.WARNING
 )
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun TestCoroutineScope(context: CoroutineContext = EmptyCoroutineContext): TestCoroutineScope {
     val scheduler = context[TestCoroutineScheduler] ?: TestCoroutineScheduler()
     return createTestCoroutineScope(TestCoroutineDispatcher(scheduler) + TestCoroutineExceptionHandler() + context)
@@ -163,6 +167,7 @@ public fun TestCoroutineScope(context: CoroutineContext = EmptyCoroutineContext)
         "Please use TestScope() construction instead, or just runTest(), without creating a scope.",
     level = DeprecationLevel.WARNING
 )
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun createTestCoroutineScope(context: CoroutineContext = EmptyCoroutineContext): TestCoroutineScope {
     val ctxWithDispatcher = context.withDelaySkipping()
     var scope: TestCoroutineScopeImpl? = null
@@ -222,6 +227,7 @@ public val TestCoroutineScope.currentTime: Long
     ReplaceWith("this.testScheduler.apply { advanceTimeBy(delayTimeMillis); runCurrent() }"),
     DeprecationLevel.WARNING
 )
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun TestCoroutineScope.advanceTimeBy(delayTimeMillis: Long): Unit =
     when (val controller = coroutineContext.delayController) {
         null -> {
@@ -265,6 +271,7 @@ public fun TestCoroutineScope.runCurrent() {
     ),
     DeprecationLevel.WARNING
 )
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public suspend fun TestCoroutineScope.pauseDispatcher(block: suspend () -> Unit) {
     delayControllerForPausing.pauseDispatcher(block)
 }
@@ -280,6 +287,7 @@ public suspend fun TestCoroutineScope.pauseDispatcher(block: suspend () -> Unit)
     ),
     level = DeprecationLevel.WARNING
 )
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun TestCoroutineScope.pauseDispatcher() {
     delayControllerForPausing.pauseDispatcher()
 }
@@ -295,6 +303,7 @@ public fun TestCoroutineScope.pauseDispatcher() {
     ),
     level = DeprecationLevel.WARNING
 )
+// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
 public fun TestCoroutineScope.resumeDispatcher() {
     delayControllerForPausing.resumeDispatcher()
 }