Stabilize EnumEntries stdlib signature

* Also, mention implementation details of EnumEntries to enable safe uses of a 'EnumEntries' as a set
* Fix testdata for opt-in marker in enum entries

^KT-58548 fixed

Merge-request: KT-MR-10037
Merged-by: Vsevolod Tolstopyatov <qwwdfsad@gmail.com>

compiler/testData/diagnostics/tests/enum/entries/conflictingPropertyEntriesAndReference.fir.kt

@@ -8,8 +8,8 @@ enum class E {
 }
 
 fun test() {
-    E::<!OPT_IN_USAGE_ERROR!>entries<!>
+    E::entries
-    val ref = E::<!OPT_IN_USAGE_ERROR!>entries<!>
+    val ref = E::entries
     val refType: (E) -> Int = E::entries
-    val refTypeWithAnyExpectedType: Any = E::<!OPT_IN_USAGE_ERROR!>entries<!>
+    val refTypeWithAnyExpectedType: Any = E::entries
 }

compiler/testData/diagnostics/tests/enum/entries/entriesPropertyAsExtensionClash.fir.kt

@@ -12,7 +12,7 @@ enum class A {
 val A.Companion.entries: Int get() = 0
 
 fun test() {
-    A.<!OPT_IN_USAGE_ERROR!>entries<!>
+    A.entries
     A.Companion.entries
 
     with(A) {
@@ -26,4 +26,4 @@ fun test() {
 
     val aCompanion = A.Companion
     aCompanion.entries
-}
+}

compiler/testData/diagnostics/tests/enum/entries/entriesPropertyAsExtensionClashOn.fir.kt

@@ -12,7 +12,7 @@ enum class A {
 val A.Companion.entries: Int get() = 0
 
 fun test() {
-    A.<!OPT_IN_USAGE_ERROR!>entries<!>
+    A.entries
     A.Companion.entries
 
     with(A) {

compiler/testData/diagnostics/tests/enum/entries/entriesPropertyImportedClash.fir.kt

@@ -14,7 +14,7 @@ enum class A {
 }
 
 fun test() {
-    A.<!OPT_IN_USAGE_ERROR!>entries<!>
+    A.entries
 
     with(A) {
         entries

compiler/testData/diagnostics/tests/enum/entries/entriesPropertyImportedClashOn.fir.kt

@@ -14,7 +14,7 @@ enum class A {
 }
 
 fun test() {
-    A.<!OPT_IN_USAGE_ERROR!>entries<!>
+    A.entries
 
     with(A) {
         entries

compiler/testData/diagnostics/tests/enum/entries/entriesPropertyInCompanionClash.fir.kt

@@ -10,7 +10,7 @@ enum class A {
 }
 
 fun test() {
-    A.<!OPT_IN_USAGE_ERROR!>entries<!>
+    A.entries
     A.Companion.entries
 
     with(A) {

compiler/testData/diagnostics/tests/enum/entries/entriesPropertyInCompanionClashOn.fir.kt

@@ -10,7 +10,7 @@ enum class A {
 }
 
 fun test() {
-    A.<!OPT_IN_USAGE_ERROR!>entries<!>
+    A.entries
     A.Companion.entries
 
     with(A) {

compiler/testData/diagnostics/tests/enum/entries/entriesPropertyWithJvmStaticClash.fir.kt

@@ -11,7 +11,7 @@ enum class A {
 }
 
 fun test() {
-    A.<!OPT_IN_USAGE_ERROR!>entries<!>
+    A.entries
 
     with(A) {
         entries

compiler/testData/diagnostics/tests/enum/entries/entriesUnsupported.fir.kt

@@ -7,5 +7,5 @@ enum class Foo {
 }
 
 fun main() {
-    Foo.<!OPT_IN_USAGE_ERROR!>entries<!>
+    Foo.entries
 }

compiler/testData/diagnostics/tests/enum/entries/entriesUnsupported.kt

@@ -7,5 +7,5 @@ enum class Foo {
 }
 
 fun main() {
-    Foo.<!OPT_IN_USAGE_ERROR, UNSUPPORTED_FEATURE!>entries<!>
+    Foo.<!UNSUPPORTED_FEATURE!>entries<!>
 }

compiler/testData/diagnostics/tests/enum/entries/genericEntriesPropertyClash.fir.kt

@@ -12,6 +12,6 @@ enum class A {
 val <T> T.entries: Int get() = 0
 
 fun test() {
-    A.<!OPT_IN_USAGE_ERROR!>entries<!>
+    A.entries
     A.Companion.entries
 }

compiler/testData/diagnostics/tests/enum/entries/javaEnumEntriesAmbiguity.fir.kt

@@ -29,5 +29,5 @@ fun test() {
     JEnumEntry.entries
     JEnumStaticField.entries
 
-    JEnumField::<!OPT_IN_USAGE_ERROR!>entries<!>
+    JEnumField::entries
 }

compiler/testData/diagnostics/tests/enum/entries/nameShadowingOfExternallyDefinedEntries.fir.kt

@@ -9,7 +9,7 @@ enum class E {
     ;
 
     fun foo() {
-        <!OPT_IN_USAGE_ERROR!>entries<!>
+        entries
         pckg.entries
     }
 }
@@ -20,7 +20,7 @@ class A {
 
         class B {
             fun foo() {
-                <!OPT_IN_USAGE_ERROR!>entries<!>
+                entries
                 pckg.entries
             }
         }

compiler/testData/diagnostics/tests/enum/entries/nameShadowingOfExternallyDefinedEntriesOn.fir.kt

@@ -9,7 +9,7 @@ enum class E {
     ;
 
     fun foo() {
-        <!OPT_IN_USAGE_ERROR!>entries<!>.<!UNRESOLVED_REFERENCE!>length<!>
+        entries.<!UNRESOLVED_REFERENCE!>length<!>
         pckg.entries.length
     }
 }
@@ -20,7 +20,7 @@ class A {
 
         class B {
             fun foo() {
-                <!OPT_IN_USAGE_ERROR!>entries<!>.<!UNRESOLVED_REFERENCE!>length<!>
+                entries.<!UNRESOLVED_REFERENCE!>length<!>
                 pckg.entries.length
             }
         }

libraries/stdlib/api/js-v1/kotlin.enums.kt

@@ -1,4 +1,4 @@
-@kotlin.ExperimentalStdlibApi
+@kotlin.SinceKotlin(version = "1.9")
-@kotlin.SinceKotlin(version = "1.8")
+@kotlin.WasExperimental(markerClass = {kotlin.ExperimentalStdlibApi::class})
 public sealed interface EnumEntries<E : kotlin.Enum<E>> : kotlin.collections.List<E> {
-}
+}

libraries/stdlib/api/js/kotlin.enums.kt

@@ -1,4 +1,4 @@
-@kotlin.ExperimentalStdlibApi
+@kotlin.SinceKotlin(version = "1.9")
-@kotlin.SinceKotlin(version = "1.8")
+@kotlin.WasExperimental(markerClass = {kotlin.ExperimentalStdlibApi::class})
 public sealed interface EnumEntries<E : kotlin.Enum<E>> : kotlin.collections.List<E> {
-}
+}

libraries/stdlib/src/kotlin/enums/EnumEntries.kt

@@ -14,23 +14,24 @@ package kotlin.enums
  * consistently with the corresponding [Enum.ordinal] values.
  *
  * An instance of this interface can only be obtained from `EnumClass.entries` property.
+ *
+ * #### Implementation note
+ * All basic operations, such as `contains` and `indexOf`, are executed in constant time and are likely to be
+ * faster than regular `ArrayList<E>` counterparts.
  */
-@ExperimentalStdlibApi
+@SinceKotlin("1.9")
-@SinceKotlin("1.8")
+@WasExperimental(ExperimentalStdlibApi::class)
 public sealed interface EnumEntries<E : Enum<E>> : List<E>
 
 @PublishedApi
-@ExperimentalStdlibApi
 @SinceKotlin("1.8") // Used by pre-1.9.0 JVM compiler for the feature in preview mode. Can be safely removed around 2.1
 internal fun <E : Enum<E>> enumEntries(entriesProvider: () -> Array<E>): EnumEntries<E> = EnumEntriesList(entriesProvider())
 
 @PublishedApi
-@ExperimentalStdlibApi
 @SinceKotlin("1.8")
 internal fun <E : Enum<E>> enumEntries(entries: Array<E>): EnumEntries<E> = EnumEntriesList(entries)
 
 @SinceKotlin("1.8")
-@ExperimentalStdlibApi
 private class EnumEntriesList<T : Enum<T>>(private val entries: Array<T>) : EnumEntries<T>, AbstractList<T>(), Serializable {
 // WA for JS IR bug:
 //  class type parameter name MUST be different from E (AbstractList<E> type parameter),