Deprecate SerializersModuleCollector.polymorphicDefault and Polymorph…

…icModuleBuilder.default (#2076)

Replaced with default polymorphicDefaultDeserializer and defaultDeserializer respectively.
Remove experimentality from SerializersModuleCollector.polymorphicDefaultSerializer.

This is a follow-up for #1686 — finishing migration path

core/commonMain/src/kotlinx/serialization/modules/PolymorphicModuleBuilder.kt

@@ -34,18 +34,19 @@ public class PolymorphicModuleBuilder<in Base : Any> @PublishedApi internal cons
      * Adds a default serializers provider associated with the given [baseClass] to the resulting module.
      * [defaultDeserializerProvider] is invoked when no polymorphic serializers associated with the `className`
      * were found. `className` could be `null` for formats that support nullable class discriminators
-     * (currently only [Json] with [useArrayPolymorphism][JsonBuilder.useArrayPolymorphism] set to `false`)
+     * (currently only `Json` with `JsonBuilder.useArrayPolymorphism` set to `false`)
+     *
+     * Default deserializers provider affects only deserialization process. To affect serialization process, use
+     * [SerializersModuleBuilder.polymorphicDefaultSerializer].
      *
      * [defaultDeserializerProvider] can be stateful and lookup a serializer for the missing type dynamically.
      *
      * Typically, if the class is not registered in advance, it is not possible to know the structure of the unknown
      * type and have a precise serializer, so the default serializer has limited capabilities.
-     * To have a structural access to the unknown data, it is recommended to use [JsonTransformingSerializer]
-     * or [JsonContentPolymorphicSerializer] classes.
+     * If you're using `Json` format, you can get a structural access to the unknown data using `JsonContentPolymorphicSerializer`.
      *
-     * Default deserializers provider affects only deserialization process.
+     * @see SerializersModuleBuilder.polymorphicDefaultSerializer
      */
-    @ExperimentalSerializationApi
     public fun defaultDeserializer(defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?) {
         require(this.defaultDeserializerProvider == null) {
             "Default deserializer provider is already registered for class $baseClass: ${this.defaultDeserializerProvider}"
@@ -55,26 +56,27 @@ public class PolymorphicModuleBuilder<in Base : Any> @PublishedApi internal cons
 
     /**
      * Adds a default deserializers provider associated with the given [baseClass] to the resulting module.
+     * This function affect only deserialization process. To avoid confusion, it was deprecated and replaced with [defaultDeserializer].
+     * To affect serialization process, use [SerializersModuleBuilder.polymorphicDefaultSerializer].
+     *
      * [defaultSerializerProvider] is invoked when no polymorphic serializers associated with the `className`
      * were found. `className` could be `null` for formats that support nullable class discriminators
-     * (currently only [Json] with [useArrayPolymorphism][JsonBuilder.useArrayPolymorphism] set to `false`)
+     * (currently only `Json` with `JsonBuilder.useArrayPolymorphism` set to `false`)
      *
      * [defaultSerializerProvider] can be stateful and lookup a serializer for the missing type dynamically.
      *
-     * [defaultSerializerProvider] is named as such for backwards compatibility reasons; it provides deserializers.
-     *
      * Typically, if the class is not registered in advance, it is not possible to know the structure of the unknown
      * type and have a precise serializer, so the default serializer has limited capabilities.
-     * To have a structural access to the unknown data, it is recommended to use [JsonTransformingSerializer]
-     * or [JsonContentPolymorphicSerializer] classes.
-     *
-     * Default deserializers provider affects only deserialization process. To affect serialization process, use
-     * [SerializersModuleBuilder.polymorphicDefaultSerializer].
+     * If you're using `Json` format, you can get a structural access to the unknown data using `JsonContentPolymorphicSerializer`.
      *
      * @see defaultDeserializer
+     * @see SerializersModuleBuilder.polymorphicDefaultSerializer
      */
-    @OptIn(ExperimentalSerializationApi::class)
-    // TODO: deprecate in 1.4
+    @Deprecated(
+        "Deprecated in favor of function with more precise name: defaultDeserializer",
+        ReplaceWith("defaultDeserializer(defaultSerializerProvider)"),
+        DeprecationLevel.WARNING // Since 1.5.0. Raise to ERROR in 1.6.0, hide in 1.7.0
+    )
     public fun default(defaultSerializerProvider: (className: String?) -> DeserializationStrategy<Base>?) {
         defaultDeserializer(defaultSerializerProvider)
     }

core/commonMain/src/kotlinx/serialization/modules/SerializersModuleBuilders.kt

@@ -97,11 +97,13 @@ public class SerializersModuleBuilder @PublishedApi internal constructor() : Ser
 
     /**
      * Adds a default serializers provider associated with the given [baseClass] to the resulting module.
-     * [defaultSerializerProvider] is invoked when no polymorphic serializers for `value` were found.
+     * [defaultSerializerProvider] is invoked when no polymorphic serializers for `value` in the scope of [baseClass] were found.
      *
-     * This will not affect deserialization.
+     * Default serializers provider affects only serialization process. To affect deserialization process, use
+     * [SerializersModuleBuilder.polymorphicDefaultDeserializer].
+     *
+     * [defaultSerializerProvider] can be stateful and lookup a serializer for the missing type dynamically.
      */
-    @ExperimentalSerializationApi
     public override fun <Base : Any> polymorphicDefaultSerializer(
         baseClass: KClass<Base>,
         defaultSerializerProvider: (value: Base) -> SerializationStrategy<Base>?
@@ -112,14 +114,16 @@ public class SerializersModuleBuilder @PublishedApi internal constructor() : Ser
     /**
      * Adds a default deserializers provider associated with the given [baseClass] to the resulting module.
      * [defaultDeserializerProvider] is invoked when no polymorphic serializers associated with the `className`
-     * were found. `className` could be `null` for formats that support nullable class discriminators
+     * in the scope of [baseClass] were found. `className` could be `null` for formats that support nullable class discriminators
      * (currently only `Json` with `useArrayPolymorphism` set to `false`).
      *
-     * This will not affect serialization.
+     * Default deserializers provider affects only deserialization process. To affect serialization process, use
+     * [SerializersModuleBuilder.polymorphicDefaultSerializer].
+     *
+     * [defaultDeserializerProvider] can be stateful and lookup a serializer for the missing type dynamically.
      *
      * @see PolymorphicModuleBuilder.defaultDeserializer
      */
-    @ExperimentalSerializationApi
     public override fun <Base : Any> polymorphicDefaultDeserializer(
         baseClass: KClass<Base>,
         defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?

core/commonMain/src/kotlinx/serialization/modules/SerializersModuleCollector.kt

@@ -47,27 +47,29 @@ public interface SerializersModuleCollector {
 
     /**
      * Accept a default serializer provider, associated with the [baseClass] for polymorphic serialization.
+     * [defaultSerializerProvider] is invoked when no polymorphic serializers for `value` in the scope of [baseClass] were found.
      *
-     * This will not affect deserialization.
+     * Default serializers provider affects only serialization process. Deserializers are accepted in the
+     * [SerializersModuleCollector.polymorphicDefaultDeserializer] method.
      *
-     * @see SerializersModuleBuilder.polymorphicDefaultSerializer
-     * @see PolymorphicModuleBuilder.defaultSerializer
+     * [defaultSerializerProvider] can be stateful and lookup a serializer for the missing type dynamically.
      */
-    @ExperimentalSerializationApi
     public fun <Base : Any> polymorphicDefaultSerializer(
         baseClass: KClass<Base>,
         defaultSerializerProvider: (value: Base) -> SerializationStrategy<Base>?
     )
 
     /**
      * Accept a default deserializer provider, associated with the [baseClass] for polymorphic deserialization.
+     * [defaultDeserializerProvider] is invoked when no polymorphic serializers associated with the `className`
+     * in the scope of [baseClass] were found. `className` could be `null` for formats that support nullable class discriminators
+     * (currently only `Json` with `useArrayPolymorphism` set to `false`).
      *
-     * This will not affect serialization.
+     * Default deserializers provider affects only deserialization process. Serializers are accepted in the
+     * [SerializersModuleCollector.polymorphicDefaultSerializer] method.
      *
-     * @see SerializersModuleBuilder.polymorphicDefaultDeserializer
-     * @see PolymorphicModuleBuilder.defaultDeserializer
+     * [defaultDeserializerProvider] can be stateful and lookup a serializer for the missing type dynamically.
      */
-    @ExperimentalSerializationApi
     public fun <Base : Any> polymorphicDefaultDeserializer(
         baseClass: KClass<Base>,
         defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?
@@ -76,12 +78,23 @@ public interface SerializersModuleCollector {
     /**
      * Accept a default deserializer provider, associated with the [baseClass] for polymorphic deserialization.
      *
-     * This will not affect serialization.
+     * This function affect only deserialization process. To avoid confusion, it was deprecated and replaced with [polymorphicDefaultDeserializer].
+     * To affect serialization process, use [SerializersModuleCollector.polymorphicDefaultSerializer].
      *
-     * @see SerializersModuleBuilder.polymorphicDefaultDeserializer
-     * @see PolymorphicModuleBuilder.defaultDeserializer
+     * [defaultDeserializerProvider] is invoked when no polymorphic serializers associated with the `className`
+     * in the scope of [baseClass] were found. `className` could be `null` for formats that support nullable class discriminators
+     * (currently only `Json` with `useArrayPolymorphism` set to `false`).
+     *
+     * [defaultDeserializerProvider] can be stateful and lookup a serializer for the missing type dynamically.
+     *
+     * @see SerializersModuleCollector.polymorphicDefaultDeserializer
+     * @see SerializersModuleCollector.polymorphicDefaultSerializer
      */
-    // TODO: deprecate in 1.4
+    @Deprecated(
+        "Deprecated in favor of function with more precise name: polymorphicDefaultDeserializer",
+        ReplaceWith("polymorphicDefaultDeserializer(baseClass, defaultDeserializerProvider)"),
+        DeprecationLevel.WARNING // Since 1.5.0. Raise to ERROR in 1.6.0, hide in 1.7.0
+    )
     public fun <Base : Any> polymorphicDefault(
         baseClass: KClass<Base>,
         defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?