Introduce @AdvancedEncodingApi and @SealedSerializationApi annotations

to be used with @SubclassOptInRequired.

These annotations allow for even more fine-grained API marking. We now can designate APIs
as public for use, but closed for implementation (@SealedSerializationApi) — the case for SerialDescriptor, which is a non-sealed interface for technical reasons.

The other annotation, @AdvancedEncodingApi is aimed to provide guidance on implementing custom encoders/decoders by pointing users to a documentation and guides.

Fixes #2366

Author: sandwwraith

buildSrc/src/main/kotlin/source-sets-conventions.gradle.kts

@@ -66,7 +66,10 @@ kotlin {
             progressiveMode = true
 
             optIn("kotlin.ExperimentalMultiplatform")
+            optIn("kotlin.ExperimentalSubclassOptIn")
+            optIn("kotlin.ExperimentalStdlibApi")
             optIn("kotlinx.serialization.InternalSerializationApi")
+            optIn("kotlinx.serialization.SealedSerializationApi")
         }
     }
 
@@ -147,7 +150,9 @@ kotlin {
     sourceSets.matching({ it.name.contains("Test") }).configureEach {
         languageSettings {
             optIn("kotlinx.serialization.InternalSerializationApi")
+            optIn("kotlinx.serialization.SealedSerializationApi")
             optIn("kotlinx.serialization.ExperimentalSerializationApi")
+            optIn("kotlinx.serialization.encoding.AdvancedEncodingApi")
         }
     }
 }

core/api/kotlinx-serialization-core.api

@@ -86,6 +86,9 @@ public final class kotlinx/serialization/SealedClassSerializer : kotlinx/seriali
 	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
 }
 
+public abstract interface annotation class kotlinx/serialization/SealedSerializationApi : java/lang/annotation/Annotation {
+}
+
 public abstract interface class kotlinx/serialization/SerialFormat {
 	public abstract fun getSerializersModule ()Lkotlinx/serialization/modules/SerializersModule;
 }
@@ -424,6 +427,9 @@ public abstract class kotlinx/serialization/encoding/AbstractEncoder : kotlinx/s
 	public fun shouldEncodeElementDefault (Lkotlinx/serialization/descriptors/SerialDescriptor;I)Z
 }
 
+public abstract interface annotation class kotlinx/serialization/encoding/AdvancedEncodingApi : java/lang/annotation/Annotation {
+}
+
 public abstract interface class kotlinx/serialization/encoding/ChunkedDecoder {
 	public abstract fun decodeStringChunked (Lkotlin/jvm/functions/Function1;)V
 }

core/api/kotlinx-serialization-core.klib.api

@@ -7,6 +7,10 @@
 // - Show declarations: true
 
 // Library unique name: <org.jetbrains.kotlinx:kotlinx-serialization-core>
+open annotation class kotlinx.serialization.encoding/AdvancedEncodingApi : kotlin/Annotation { // kotlinx.serialization.encoding/AdvancedEncodingApi|null[0]
+    constructor <init>() // kotlinx.serialization.encoding/AdvancedEncodingApi.<init>|<init>(){}[0]
+}
+
 open annotation class kotlinx.serialization.internal/NamedCompanion : kotlin/Annotation { // kotlinx.serialization.internal/NamedCompanion|null[0]
     constructor <init>() // kotlinx.serialization.internal/NamedCompanion.<init>|<init>(){}[0]
 }
@@ -61,6 +65,10 @@ open annotation class kotlinx.serialization/Required : kotlin/Annotation { // ko
     constructor <init>() // kotlinx.serialization/Required.<init>|<init>(){}[0]
 }
 
+open annotation class kotlinx.serialization/SealedSerializationApi : kotlin/Annotation { // kotlinx.serialization/SealedSerializationApi|null[0]
+    constructor <init>() // kotlinx.serialization/SealedSerializationApi.<init>|<init>(){}[0]
+}
+
 open annotation class kotlinx.serialization/SerialInfo : kotlin/Annotation { // kotlinx.serialization/SerialInfo|null[0]
     constructor <init>() // kotlinx.serialization/SerialInfo.<init>|<init>(){}[0]
 }

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

@@ -377,3 +377,17 @@ public annotation class ExperimentalSerializationApi
 @Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY, AnnotationTarget.FUNCTION, AnnotationTarget.TYPEALIAS)
 @RequiresOptIn(level = RequiresOptIn.Level.ERROR)
 public annotation class InternalSerializationApi
+
+/**
+ * Marks interfaces and non-final classes that can be freely referenced in users' code but should not be
+ * implemented or inherited. Such declarations are effectively `sealed` and do not have this modifier purely for technical reasons.
+ *
+ * kotlinx.serialization library provides compatibility guarantees for existing signatures of such classes;
+ * however, new functions or properties can be added to them in any release.
+ */
+@MustBeDocumented
+@Target(AnnotationTarget.CLASS)
+@RequiresOptIn(message = "This class or interface should not be inherited/implemented outside of kotlinx.serialization library. " +
+    "Note it is still permitted to use it directly. Read its documentation about inheritance for details.", level = RequiresOptIn.Level.ERROR)
+public annotation class SealedSerializationApi
+

core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptor.kt

@@ -142,6 +142,7 @@ import kotlinx.serialization.encoding.*
  * might be added to this interface when kotlinx.serialization adds support for new Kotlin features.
  * This interface is safe to use and construct via [buildClassSerialDescriptor], [PrimitiveSerialDescriptor], and `SerialDescriptor` factory function.
  */
+@SubclassOptInRequired(SealedSerializationApi::class)
 public interface SerialDescriptor {
     /**
      * Serial name of the descriptor that identifies a pair of the associated serializer and target class.

core/commonMain/src/kotlinx/serialization/encoding/AbstractDecoder.kt

@@ -14,6 +14,7 @@ import kotlinx.serialization.descriptors.*
  * See [Decoder] documentation for information about each particular `decode*` method.
  */
 @ExperimentalSerializationApi
+@SubclassOptInRequired(AdvancedEncodingApi::class)
 public abstract class AbstractDecoder : Decoder, CompositeDecoder {
 
     /**

core/commonMain/src/kotlinx/serialization/encoding/AbstractEncoder.kt

@@ -16,6 +16,7 @@ import kotlinx.serialization.internal.*
  * See [Encoder] documentation for information about each particular `encode*` method.
  */
 @ExperimentalSerializationApi
+@SubclassOptInRequired(AdvancedEncodingApi::class)
 public abstract class AbstractEncoder : Encoder, CompositeEncoder {
 
     override fun beginStructure(descriptor: SerialDescriptor): CompositeEncoder = this

core/commonMain/src/kotlinx/serialization/encoding/Decoding.kt

@@ -111,6 +111,7 @@ import kotlinx.serialization.modules.*
  * `Decoder` interface is not stable for inheritance in 3rd-party libraries, as new methods
  * might be added to this interface or contracts of the existing methods can be changed.
  */
+@SubclassOptInRequired(AdvancedEncodingApi::class)
 public interface Decoder {
     /**
      * Context of the current serialization process, including contextual and polymorphic serialization and,
@@ -292,6 +293,7 @@ internal inline fun <T : Any> Decoder.decodeIfNullable(deserializer: Deserializa
  * `CompositeDecoder` interface is not stable for inheritance in 3rd party libraries, as new methods
  * might be added to this interface or contracts of the existing methods can be changed.
  */
+@SubclassOptInRequired(AdvancedEncodingApi::class)
 public interface CompositeDecoder {
 
     /**

core/commonMain/src/kotlinx/serialization/encoding/Encoding.kt

@@ -107,6 +107,7 @@ import kotlinx.serialization.modules.*
  * `Encoder` interface is not stable for inheritance in 3rd party libraries, as new methods
  * might be added to this interface or contracts of the existing methods can be changed.
  */
+@SubclassOptInRequired(AdvancedEncodingApi::class)
 public interface Encoder {
     /**
      * Context of the current serialization process, including contextual and polymorphic serialization and,
@@ -320,6 +321,7 @@ public interface Encoder {
  * `CompositeEncoder` interface is not stable for inheritance in 3rd party libraries, as new methods
  * might be added to this interface or contracts of the existing methods can be changed.
  */
+@SubclassOptInRequired(AdvancedEncodingApi::class)
 public interface CompositeEncoder {
     /**
      * Context of the current serialization process, including contextual and polymorphic serialization and,

core/commonMain/src/kotlinx/serialization/encoding/EncodingSubclassAnnotation.kt

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2017-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.serialization.encoding
+
+/**
+ * Marks all encoding- and decoding-related interfaces in kotlinx.serialization.
+ * These interfaces are used in serializers and have to be implemented only if you want to write
+ * a custom serialization format. Since encoder/decoder invariants are quite complex,
+ * it is recommended to start with reading their documentation: see [Encoder] and [Decoder],
+ * and [kotlinx.serialization guide](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/formats.md#custom-formats-experimental) about them.
+ * There are also existing skeleton implementations that you may find useful: [AbstractEncoder] and [AbstractDecoder].
+ */
+@RequiresOptIn(
+    "You should implement Encoder or Decoder only if you want to write a custom kotlinx.serialization format. " +
+        "Before doing so, please consult official guide at https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/formats.md#custom-formats-experimental",
+    level = RequiresOptIn.Level.WARNING
+)
+public annotation class AdvancedEncodingApi