feat(#177): add 'ExperimentalCollectionApi' annotation

CHANGELOG.md

@@ -22,6 +22,14 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+#### Experimental annotation for collections
+
+This version introduces an `ExperimentalCollectionApi` annotation in the
+`kotools.types.experimental` package for marking experimental declarations
+of the `kotools.types.collection` package (issue [#177]).
+
+[#177]: https://github.com/kotools/types/issues/177
+
 #### Experimental builders suffixed by `OrNull` and `OrThrow`
 
 For aligning with Kotlin standards incrementally, like discussed in the idea

api/types.api

@@ -103,6 +103,9 @@ public final class kotools/types/collection/NotEmptySetKt {
 	public static final fun toNotEmptySet (Ljava/util/Collection;)Ljava/lang/Object;
 }
 
+public abstract interface annotation class kotools/types/experimental/ExperimentalCollectionApi : java/lang/annotation/Annotation {
+}
+
 public abstract interface annotation class kotools/types/experimental/ExperimentalNumberApi : java/lang/annotation/Annotation {
 }
 

src/commonMain/kotlin/kotools/types/experimental/Annotations.kt

@@ -2,7 +2,18 @@ package kotools.types.experimental
 
 import kotools.types.SinceKotoolsTypes
 import kotlin.annotation.AnnotationRetention.BINARY
-import kotlin.annotation.AnnotationTarget.*
+import kotlin.annotation.AnnotationTarget.CLASS
+import kotlin.annotation.AnnotationTarget.FUNCTION
+import kotlin.annotation.AnnotationTarget.PROPERTY
+import kotlin.annotation.AnnotationTarget.TYPEALIAS
+
+/** Marks declarations that are still **experimental** in the collection API. */
+@MustBeDocumented
+@RequiresOptIn
+@Retention(BINARY)
+@SinceKotoolsTypes("4.4")
+@Target(CLASS, FUNCTION, PROPERTY, TYPEALIAS)
+public annotation class ExperimentalCollectionApi
 
 /** Marks declarations that are still **experimental** in the number API. */
 @MustBeDocumented