Rework opt-ins in build scripts (#2794)

* Move opt-in configurations from AbstractKotlinCompile compiler flags

because AbstractKotlinCompile is a base type only for JVM & JS compilations, so this way of configuration is incorrect.
Furthermore, we should not opt-in for every module in the project.

Corresponding opt-ins were moved to projects' build scripts where appropriate.

* Mark-up documentation with @ExperimentalSerializationApi where needed

becuase :guide project does not have global opt-in into it.

* Add @ExperimentalSerializationApi to @KeepGeneratedSerializer

because this is a new feature.

build.gradle.kts

@@ -94,11 +94,7 @@ tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinNativeCompile>().configur
 
 subprojects {
     tasks.withType<org.jetbrains.kotlin.gradle.tasks.AbstractKotlinCompile<*>>().configureEach {
-        if (name.contains("Test") || name.contains("Jmh")) {
-            compilerOptions.freeCompilerArgs.addAll(experimentalsInTestEnabled)
-        } else {
-            compilerOptions.freeCompilerArgs.addAll(experimentalsEnabled)
-        }
+        compilerOptions.freeCompilerArgs.addAll(globalCompilerArgs)
     }
 }
 
@@ -172,18 +168,8 @@ gradle.taskGraph.whenReady {
 // getters are required because of variable lazy initialization in Gradle
 val unpublishedProjects get() = setOf("benchmark", "guide", "kotlinx-serialization-json-tests")
 val excludedFromBomProjects get() = unpublishedProjects + "kotlinx-serialization-bom"
-val experimentalsEnabled get() = listOf(
-    "-progressive",
-    "-opt-in=kotlin.ExperimentalMultiplatform",
-    "-opt-in=kotlinx.serialization.InternalSerializationApi",
-    "-P", "plugin:org.jetbrains.kotlinx.serialization:disableIntrinsic=false"
-)
-
-val experimentalsInTestEnabled get() = listOf(
-    "-progressive",
-    "-opt-in=kotlin.ExperimentalMultiplatform",
-    "-opt-in=kotlinx.serialization.ExperimentalSerializationApi",
-    "-opt-in=kotlinx.serialization.InternalSerializationApi",
+val globalCompilerArgs
+    get() = listOf(
     "-P", "plugin:org.jetbrains.kotlinx.serialization:disableIntrinsic=false"
 )
 

core/commonMain/src/kotlinx/serialization/Annotations.kt

@@ -341,8 +341,9 @@ public annotation class Polymorphic
  * Annotation is not allowed on classes involved in polymorphic serialization:
  * interfaces, sealed classes, abstract classes, classes marked by [Polymorphic].
  *
- * A compiler version `2.0.20` and higher is required.
+ * A compiler version `2.0.20` or higher is required.
  */
+@ExperimentalSerializationApi
 @Target(AnnotationTarget.CLASS)
 @Retention(AnnotationRetention.RUNTIME)
 public annotation class KeepGeneratedSerializer

docs/basic-serialization.md

@@ -450,6 +450,7 @@ For that purposes, [EncodeDefault] annotation can be used:
 
 ```kotlin
 @Serializable
+@OptIn(ExperimentalSerializationApi::class) // EncodeDefault is an experimental annotation for now
 data class Project(
     val name: String,
     @EncodeDefault val language: String = "Kotlin"
@@ -462,6 +463,7 @@ It's also possible to tweak it into the opposite behavior using [EncodeDefault.M
 ```kotlin
 
 @Serializable
+@OptIn(ExperimentalSerializationApi::class) // EncodeDefault is an experimental annotation for now
 data class User(
     val name: String,
     @EncodeDefault(EncodeDefault.Mode.NEVER) val projects: List<Project> = emptyList()