Introduce @ExperimentalEncodingApi for binary-to-text encoding API

2023-01-16 08:38:13 +02:00
parent dc03a03762
commit 954ec1f63c
4 changed files with 58 additions and 0 deletions
@@ -0,0 +1,37 @@
+/*
+ * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.io.encoding
+
+import kotlin.annotation.AnnotationTarget.*
+
+/**
+ * This annotation marks the experimental API for encoding and decoding between binary data and printable ASCII character sequences.
+ *
+ * > 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 `@ExperimentalEncodingApi` must be accepted either by
+ * annotating that usage with the [OptIn] annotation, e.g. `@OptIn(ExperimentalEncodingApi::class)`,
+ * or by using the compiler argument `-opt-in=kotlin.io.encoding.ExperimentalEncodingApi`.
+ */
+@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
+@Retention(AnnotationRetention.BINARY)
+@Target(
+    CLASS,
+    ANNOTATION_CLASS,
+    PROPERTY,
+    FIELD,
+    LOCAL_VARIABLE,
+    VALUE_PARAMETER,
+    CONSTRUCTOR,
+    FUNCTION,
+    PROPERTY_GETTER,
+    PROPERTY_SETTER,
+    TYPEALIAS
+)
+@MustBeDocumented
+@SinceKotlin("1.8")
+public annotation class ExperimentalEncodingApi