diff --git a/core/commonMain/src/kotlinx/serialization/modules/PolymorphicModuleBuilder.kt b/core/commonMain/src/kotlinx/serialization/modules/PolymorphicModuleBuilder.kt index 31ce45740..dd57b915a 100644 --- a/core/commonMain/src/kotlinx/serialization/modules/PolymorphicModuleBuilder.kt +++ b/core/commonMain/src/kotlinx/serialization/modules/PolymorphicModuleBuilder.kt @@ -34,18 +34,19 @@ public class PolymorphicModuleBuilder @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?) { require(this.defaultDeserializerProvider == null) { "Default deserializer provider is already registered for class $baseClass: ${this.defaultDeserializerProvider}" @@ -55,26 +56,23 @@ public class PolymorphicModuleBuilder @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)")) public fun default(defaultSerializerProvider: (className: String?) -> DeserializationStrategy?) { defaultDeserializer(defaultSerializerProvider) } diff --git a/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleBuilders.kt b/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleBuilders.kt index c24fe9648..28064bc3f 100644 --- a/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleBuilders.kt +++ b/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 polymorphicDefaultSerializer( baseClass: KClass, defaultSerializerProvider: (value: Base) -> SerializationStrategy? @@ -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 polymorphicDefaultDeserializer( baseClass: KClass, defaultDeserializerProvider: (className: String?) -> DeserializationStrategy? diff --git a/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleCollector.kt b/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleCollector.kt index c4af77f85..dd86bebf6 100644 --- a/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleCollector.kt +++ b/core/commonMain/src/kotlinx/serialization/modules/SerializersModuleCollector.kt @@ -47,13 +47,13 @@ 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 polymorphicDefaultSerializer( baseClass: KClass, defaultSerializerProvider: (value: Base) -> SerializationStrategy? @@ -61,13 +61,15 @@ public interface SerializersModuleCollector { /** * 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 polymorphicDefaultDeserializer( baseClass: KClass, defaultDeserializerProvider: (className: String?) -> DeserializationStrategy? @@ -76,12 +78,22 @@ 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)") + ) public fun polymorphicDefault( baseClass: KClass, defaultDeserializerProvider: (className: String?) -> DeserializationStrategy?