Deprecate Experimental/UseExperimental in favor of RequiresOptIn/OptIn

libraries/stdlib/js/src/kotlin/annotations.kt

@@ -170,6 +170,7 @@ public annotation class JsQualifier(val value: String)
  * the [OptIn] annotation, e.g. `@OptIn(ExperimentalJsExport::class)`,
  * or with the `-Xopt-in=kotlin.js.ExperimentalJsExport` compiler option is given.
  */
+@Suppress("DEPRECATION")
 @Experimental(level = Experimental.Level.WARNING)
 @RequiresOptIn(level = RequiresOptIn.Level.WARNING)
 @SinceKotlin("1.3")

libraries/stdlib/src/kotlin/annotations/Experimental.kt

@@ -19,13 +19,13 @@ import kotlin.reflect.KClass
  * and its call sites should accept the experimental aspect of it either by using [UseExperimental],
  * or by being annotated with that marker themselves, effectively causing further propagation of that experimental aspect.
  *
- * This class is experimental itself and can only be used with the compiler argument `-Xuse-experimental=kotlin.Experimental`.
+ * This class is deprecated in favor of a more general approach provided by [RequiresOptIn]/[OptIn].
  */
 @Target(ANNOTATION_CLASS)
 @Retention(BINARY)
 @SinceKotlin("1.2")
 @RequireKotlin("1.2.50", versionKind = RequireKotlinVersionKind.COMPILER_VERSION)
-@Suppress("ANNOTATION_CLASS_MEMBER")
+@Deprecated("Please use RequiresOptIn instead.")
 public annotation class Experimental(val level: Level = Level.ERROR) {
     /**
      * Severity of the diagnostic that should be reported on usages of experimental API which did not explicitly accept the experimental aspect
@@ -43,7 +43,7 @@ public annotation class Experimental(val level: Level = Level.ERROR) {
  * Allows to use experimental API denoted by the given markers in the annotated file, declaration, or expression.
  * If a declaration is annotated with [UseExperimental], its usages are **not** required to opt-in to that experimental API.
  *
- * This class is experimental itself and can only be used with the compiler argument `-Xuse-experimental=kotlin.Experimental`.
+ * This class is deprecated in favor of a more general approach provided by [RequiresOptIn]/[OptIn].
  */
 @Target(
     CLASS, PROPERTY, LOCAL_VARIABLE, VALUE_PARAMETER, CONSTRUCTOR, FUNCTION, PROPERTY_GETTER, PROPERTY_SETTER, EXPRESSION, FILE, TYPEALIAS
@@ -51,6 +51,7 @@ public annotation class Experimental(val level: Level = Level.ERROR) {
 @Retention(SOURCE)
 @SinceKotlin("1.2")
 @RequireKotlin("1.2.50", versionKind = RequireKotlinVersionKind.COMPILER_VERSION)
+@Deprecated("Please use OptIn instead.", ReplaceWith("OptIn(*markerClass)", "kotlin.OptIn"))
 public annotation class UseExperimental(
     vararg val markerClass: KClass<out Annotation>
 )

libraries/stdlib/src/kotlin/annotations/ExperimentalStdlibApi.kt

@@ -14,6 +14,7 @@ import kotlin.annotation.AnnotationTarget.*
  * annotating that usage with the [OptIn] annotation, e.g. `@OptIn(ExperimentalStdlibApi::class)`,
  * or by using the compiler argument `-Xopt-in=kotlin.ExperimentalStdlibApi`.
  */
+@Suppress("DEPRECATION")
 @Experimental(level = Experimental.Level.ERROR)
 @RequiresOptIn(level = RequiresOptIn.Level.ERROR)
 @Retention(AnnotationRetention.BINARY)

libraries/stdlib/src/kotlin/annotations/Multiplatform.kt

@@ -16,6 +16,7 @@ import kotlin.internal.RequireKotlinVersionKind
  * annotating that usage with the [OptIn] annotation, e.g. `@OptIn(ExperimentalMultiplatform::class)`,
  * or by using the compiler argument `-Xopt-in=kotlin.ExperimentalMultiplatform`.
  */
+@Suppress("DEPRECATION")
 @Experimental
 @RequiresOptIn
 @MustBeDocumented

libraries/stdlib/src/kotlin/contracts/ContractBuilder.kt

@@ -16,6 +16,7 @@ import kotlin.internal.InlineOnly
  * annotating that usage with the [OptIn] annotation, e.g. `@OptIn(ExperimentalContracts::class)`,
  * or by using the compiler argument `-Xopt-in=kotlin.contracts.ExperimentalContracts`.
  */
+@Suppress("DEPRECATION")
 @Retention(AnnotationRetention.BINARY)
 @SinceKotlin("1.3")
 @Experimental

libraries/stdlib/src/kotlin/experimental/inferenceMarker.kt

@@ -12,6 +12,7 @@ package kotlin.experimental
  * annotating that usage with the [OptIn] annotation, e.g. `@OptIn(ExperimentalTypeInference::class)`,
  * or by using the compiler argument `-Xopt-in=kotlin.experimental.ExperimentalTypeInference`.
  */
+@Suppress("DEPRECATION")
 @Experimental(level = Experimental.Level.ERROR)
 @RequiresOptIn(level = RequiresOptIn.Level.ERROR)
 @MustBeDocumented

libraries/stdlib/src/kotlin/time/ExperimentalTime.kt

@@ -18,6 +18,7 @@ import kotlin.annotation.AnnotationTarget.*
  * annotating that usage with the [OptIn] annotation, e.g. `@OptIn(ExperimentalTime::class)`,
  * or by using the compiler argument `-Xopt-in=kotlin.time.ExperimentalTime`.
  */
+@Suppress("DEPRECATION")
 @Experimental(level = Experimental.Level.ERROR)
 @RequiresOptIn(level = RequiresOptIn.Level.ERROR)
 @MustBeDocumented

libraries/stdlib/unsigned/src/kotlin/annotations/Unsigned.kt

@@ -19,6 +19,7 @@ import kotlin.internal.RequireKotlinVersionKind
  *
  * It's recommended to propagate the experimental status to the API that depends on unsigned types by annotating it with this annotation.
  */
+@Suppress("DEPRECATION")
 @Experimental(level = Experimental.Level.WARNING)
 @RequiresOptIn(level = RequiresOptIn.Level.WARNING)
 @MustBeDocumented