From 6f5504e59b73a5bde25e2d82fc6516a28d606873 Mon Sep 17 00:00:00 2001
From: Abduqodiri Qurbonzoda <abduqodiri.qurbonzoda@jetbrains.com>
Date: Mon, 3 Apr 2023 15:27:02 +0300
Subject: [PATCH] [K/N] Introduce ExperimentalNativeApi annotation

An opt-in annotation to mark the Kotlin/Native-only standard library API
we doubt that eventually will be stabilized.

As a part of efforts to stabilize Native stdlib #KT-55765.
---
 .../src/main/kotlin/kotlin/Experimental.kt    | 12 ------
 .../kotlin/kotlin/ExperimentalNativeApi.kt    | 39 +++++++++++++++++++
 2 files changed, 39 insertions(+), 12 deletions(-)
 delete mode 100644 kotlin-native/runtime/src/main/kotlin/kotlin/Experimental.kt
 create mode 100644 kotlin-native/runtime/src/main/kotlin/kotlin/ExperimentalNativeApi.kt

diff --git a/kotlin-native/runtime/src/main/kotlin/kotlin/Experimental.kt b/kotlin-native/runtime/src/main/kotlin/kotlin/Experimental.kt
deleted file mode 100644
index cc5065c55e7..00000000000
--- a/kotlin-native/runtime/src/main/kotlin/kotlin/Experimental.kt
+++ /dev/null
@@ -1,12 +0,0 @@
-/*
- * Copyright 2010-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license
- * that can be found in the LICENSE file.
- */
-
-/**
- * Empty package to avoid unresolved reference errors in bitwiseOp tests
- * (e.g. external_codegen_box_binaryOp/bitwiseOp.kt).
- * Byte/Short bitwise operations are supported in Kotlin Native by default.
- */
-
-package kotlin.experimental
\ No newline at end of file
diff --git a/kotlin-native/runtime/src/main/kotlin/kotlin/ExperimentalNativeApi.kt b/kotlin-native/runtime/src/main/kotlin/kotlin/ExperimentalNativeApi.kt
new file mode 100644
index 00000000000..266e3b9711f
--- /dev/null
+++ b/kotlin-native/runtime/src/main/kotlin/kotlin/ExperimentalNativeApi.kt
@@ -0,0 +1,39 @@
+/*
+ * Copyright 2010-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license
+ * that can be found in the LICENSE file.
+ */
+
+package kotlin.experimental
+
+import kotlin.annotation.AnnotationTarget.*
+
+/**
+ * This annotation marks the Kotlin/Native-only standard library API that is considered experimental and is not subject to the
+ * [general compatibility guarantees](https://kotlinlang.org/docs/reference/evolution/components-stability.html) given for the standard library:
+ * the behavior of such API may be changed or the API may be removed completely in any further release.
+ *
+ * > Beware using the annotated API especially if you're developing a library, since your library might become binary incompatible
+ * with the future versions of the standard library.
+ *
+ * Any usage of a declaration annotated with `@ExperimentalNativeApi` must be accepted either by
+ * annotating that usage with the [OptIn] annotation, e.g. `@OptIn(ExperimentalNativeApi::class)`,
+ * or by using the compiler argument `-opt-in=kotlin.native.ExperimentalNativeApi`.
+ */
+@RequiresOptIn(level = RequiresOptIn.Level.WARNING)
+@Retention(AnnotationRetention.BINARY)
+@Target(
+        AnnotationTarget.CLASS,
+        AnnotationTarget.ANNOTATION_CLASS,
+        AnnotationTarget.PROPERTY,
+        AnnotationTarget.FIELD,
+        AnnotationTarget.LOCAL_VARIABLE,
+        AnnotationTarget.VALUE_PARAMETER,
+        AnnotationTarget.CONSTRUCTOR,
+        AnnotationTarget.FUNCTION,
+        AnnotationTarget.PROPERTY_GETTER,
+        AnnotationTarget.PROPERTY_SETTER,
+        AnnotationTarget.TYPEALIAS
+)
+@MustBeDocumented
+@SinceKotlin("1.9")
+public annotation class ExperimentalNativeApi
\ No newline at end of file