Address pull request comments:

- Rename subClassesOf to subClassesOfSealed - also update the function documentation.
- Add a check for open polymorphic children (rather than leaving this to failure on format initialisation/validation).
- Add a test that the open children will throw an exception
- Fix/enhance the documentation extension
- Update the apiDump

Author: pdvrieze

core/api/kotlinx-serialization-core.api

@@ -1334,6 +1334,7 @@ public final class kotlinx/serialization/modules/PolymorphicModuleBuilder {
 	public final fun default (Lkotlin/jvm/functions/Function1;)V
 	public final fun defaultDeserializer (Lkotlin/jvm/functions/Function1;)V
 	public final fun subclass (Lkotlin/reflect/KClass;Lkotlinx/serialization/KSerializer;)V
+	public final fun subclassesOfSealed (Lkotlinx/serialization/KSerializer;)V
 }
 
 public abstract class kotlinx/serialization/modules/SerializersModule {

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

@@ -527,9 +527,11 @@ final class <#A: in kotlin/Any> kotlinx.serialization.modules/PolymorphicModuleB
     constructor <init>(kotlin.reflect/KClass<#A>, kotlinx.serialization/KSerializer<#A>? = ...) // kotlinx.serialization.modules/PolymorphicModuleBuilder.<init>|<init>(kotlin.reflect.KClass<1:0>;kotlinx.serialization.KSerializer<1:0>?){}[0]
 
     final fun <#A1: #A> subclass(kotlin.reflect/KClass<#A1>, kotlinx.serialization/KSerializer<#A1>) // kotlinx.serialization.modules/PolymorphicModuleBuilder.subclass|subclass(kotlin.reflect.KClass<0:0>;kotlinx.serialization.KSerializer<0:0>){0§<1:0>}[0]
+    final fun <#A1: #A> subclassesOfSealed(kotlinx.serialization/KSerializer<#A1>) // kotlinx.serialization.modules/PolymorphicModuleBuilder.subclassesOfSealed|subclassesOfSealed(kotlinx.serialization.KSerializer<0:0>){0§<1:0>}[0]
     final fun buildTo(kotlinx.serialization.modules/SerializersModuleBuilder) // kotlinx.serialization.modules/PolymorphicModuleBuilder.buildTo|buildTo(kotlinx.serialization.modules.SerializersModuleBuilder){}[0]
     final fun default(kotlin/Function1<kotlin/String?, kotlinx.serialization/DeserializationStrategy<#A>?>) // kotlinx.serialization.modules/PolymorphicModuleBuilder.default|default(kotlin.Function1<kotlin.String?,kotlinx.serialization.DeserializationStrategy<1:0>?>){}[0]
     final fun defaultDeserializer(kotlin/Function1<kotlin/String?, kotlinx.serialization/DeserializationStrategy<#A>?>) // kotlinx.serialization.modules/PolymorphicModuleBuilder.defaultDeserializer|defaultDeserializer(kotlin.Function1<kotlin.String?,kotlinx.serialization.DeserializationStrategy<1:0>?>){}[0]
+    final inline fun <#A1: reified #A> subclassesOfSealed() // kotlinx.serialization.modules/PolymorphicModuleBuilder.subclassesOfSealed|subclassesOfSealed(){0§<1:0>}[0]
 }
 
 final class <#A: kotlin/Any, #B: #A?> kotlinx.serialization.internal/ReferenceArraySerializer : kotlinx.serialization.internal/CollectionLikeSerializer<#B, kotlin/Array<#B>, kotlin.collections/ArrayList<#B>> { // kotlinx.serialization.internal/ReferenceArraySerializer|null[0]
@@ -1168,6 +1170,7 @@ final inline fun (kotlinx.serialization.encoding/Encoder).kotlinx.serialization.
 final inline fun (kotlinx.serialization.encoding/Encoder).kotlinx.serialization.encoding/encodeStructure(kotlinx.serialization.descriptors/SerialDescriptor, crossinline kotlin/Function1<kotlinx.serialization.encoding/CompositeEncoder, kotlin/Unit>) // kotlinx.serialization.encoding/encodeStructure|encodeStructure@kotlinx.serialization.encoding.Encoder(kotlinx.serialization.descriptors.SerialDescriptor;kotlin.Function1<kotlinx.serialization.encoding.CompositeEncoder,kotlin.Unit>){}[0]
 final inline fun <#A: kotlin/Any, #B: reified #A> (kotlinx.serialization.modules/PolymorphicModuleBuilder<#A>).kotlinx.serialization.modules/subclass(kotlin.reflect/KClass<#B>) // kotlinx.serialization.modules/subclass|subclass@kotlinx.serialization.modules.PolymorphicModuleBuilder<0:0>(kotlin.reflect.KClass<0:1>){0§<kotlin.Any>;1§<0:0>}[0]
 final inline fun <#A: kotlin/Any, #B: reified #A> (kotlinx.serialization.modules/PolymorphicModuleBuilder<#A>).kotlinx.serialization.modules/subclass(kotlinx.serialization/KSerializer<#B>) // kotlinx.serialization.modules/subclass|subclass@kotlinx.serialization.modules.PolymorphicModuleBuilder<0:0>(kotlinx.serialization.KSerializer<0:1>){0§<kotlin.Any>;1§<0:0>}[0]
+final inline fun <#A: kotlin/Any, #B: reified #A> (kotlinx.serialization.modules/PolymorphicModuleBuilder<#A>).kotlinx.serialization.modules/subclassesOfSealed(kotlin.reflect/KClass<#B>) // kotlinx.serialization.modules/subclassesOfSealed|subclassesOfSealed@kotlinx.serialization.modules.PolymorphicModuleBuilder<0:0>(kotlin.reflect.KClass<0:1>){0§<kotlin.Any>;1§<0:0>}[0]
 final inline fun <#A: kotlin/Any> (kotlinx.serialization.modules/SerializersModuleBuilder).kotlinx.serialization.modules/polymorphic(kotlin.reflect/KClass<#A>, kotlinx.serialization/KSerializer<#A>? = ..., kotlin/Function1<kotlinx.serialization.modules/PolymorphicModuleBuilder<#A>, kotlin/Unit> = ...) // kotlinx.serialization.modules/polymorphic|polymorphic@kotlinx.serialization.modules.SerializersModuleBuilder(kotlin.reflect.KClass<0:0>;kotlinx.serialization.KSerializer<0:0>?;kotlin.Function1<kotlinx.serialization.modules.PolymorphicModuleBuilder<0:0>,kotlin.Unit>){0§<kotlin.Any>}[0]
 final inline fun <#A: kotlin/Any?> (kotlinx.serialization.encoding/Decoder).kotlinx.serialization.encoding/decodeStructure(kotlinx.serialization.descriptors/SerialDescriptor, crossinline kotlin/Function1<kotlinx.serialization.encoding/CompositeDecoder, #A>): #A // kotlinx.serialization.encoding/decodeStructure|decodeStructure@kotlinx.serialization.encoding.Decoder(kotlinx.serialization.descriptors.SerialDescriptor;kotlin.Function1<kotlinx.serialization.encoding.CompositeDecoder,0:0>){0§<kotlin.Any?>}[0]
 final inline fun <#A: kotlin/Any?> (kotlinx.serialization.encoding/Encoder).kotlinx.serialization.encoding/encodeCollection(kotlinx.serialization.descriptors/SerialDescriptor, kotlin.collections/Collection<#A>, crossinline kotlin/Function3<kotlinx.serialization.encoding/CompositeEncoder, kotlin/Int, #A, kotlin/Unit>) // kotlinx.serialization.encoding/encodeCollection|encodeCollection@kotlinx.serialization.encoding.Encoder(kotlinx.serialization.descriptors.SerialDescriptor;kotlin.collections.Collection<0:0>;kotlin.Function3<kotlinx.serialization.encoding.CompositeEncoder,kotlin.Int,0:0,kotlin.Unit>){0§<kotlin.Any?>}[0]

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

@@ -5,6 +5,7 @@
 package kotlinx.serialization.modules
 
 import kotlinx.serialization.*
+import kotlinx.serialization.descriptors.*
 import kotlinx.serialization.internal.*
 import kotlin.reflect.*
 
@@ -25,21 +26,70 @@ public class PolymorphicModuleBuilder<in Base : Any> @PublishedApi internal cons
 
 
     /**
-     * Registers the child serializers for the sealed [subclass] [serializer] in the resulting module under the [base class][Base].
+     * Registers the child serializers for the sealed [subclass] [serializer] in the resulting module under
+     * the [base class][Base]. Please note that type `T` must be sealed, if not a runtime error will
+     * be thrown at registration time. This function is a convenience function for the version that
+     * receives a serializer.
+     *
+     *
+     * Example:
+     * ```kotlin
+     * interface Base
+     *
+     * @Serializable
+     * sealed interface Sub
+     *
+     * @Serializable
+     * class Sub1: Sub
+     *
+     * serializersModule {
+     *   polymorphic(Base::class) {
+     *      subclassesOfSealed<Sub>()
+     *   }
+     * }
+     * ```
      */
-    public inline fun <reified T : Base> subclassesOf(): Unit =
-        subclassesOf(serializer<T>())
+    @ExperimentalSerializationApi
+    public inline fun <reified T : Base> subclassesOfSealed(): Unit =
+        subclassesOfSealed(serializer<T>())
 
 
     /**
-     * Registers the subclasses of the given class as subclasses of the outer class. This currently requires `baseClass`
-     * to be sealed.
+     * Registers the subclasses of the given class as subclasses of the outer class. This currently
+     * requires `serializer` to be sealed. If not a runtime error will be thrown at registration time.
+     *
+     * Example:
+     * ```kotlin
+     * interface Base
+     *
+     * @Serializable
+     * sealed interface Sub
+     *
+     * @Serializable
+     * class Sub1: Sub
+     *
+     * serializersModule {
+     *   polymorphic(Base::class) {
+     *      subclassesOfSealed(Sub.serializer())
+     *   }
+     * }
+     * ```
+     *
+     * It is an error if th
      */
-    public fun <T: Base> subclassesOf(serializer: KSerializer<T>) {
+    @ExperimentalSerializationApi
+    public fun <T: Base> subclassesOfSealed(serializer: KSerializer<T>) {
+        // Note that the parameter type is `KSerializer` as `SealedClassSerializer` is an internal type
+        // not available to users
         require(serializer is SealedClassSerializer) {
             "subClassesOf only supports automatic adding of subclasses of sealed types."
         }
         for ((subsubclass, subserializer) in serializer.class2Serializer.entries) {
+            // This error would be caught by the Json format in its validation, but this is format specific
+            require (subserializer.descriptor.kind != PolymorphicKind.OPEN) {
+                "It is not possible to register subclasses of sealed types when those subclasses " +
+                    "themselves are (open) polymorphic, as this would represent an incomplete hierarchy"
+            }
             @Suppress("UNCHECKED_CAST")
             // We don't know the type here, but it matches if correct in the sealed serializer.
             subclass(subsubclass as KClass<T>, subserializer as KSerializer<T>)
@@ -143,5 +193,6 @@ public inline fun <Base : Any, reified T : Base> PolymorphicModuleBuilder<Base>.
 /**
  * Registers the child serializers for the sealed class [T] in the resulting module under the [base class][Base].
  */
-public inline fun <Base : Any, reified T : Base> PolymorphicModuleBuilder<Base>.subclassesOf(clazz: KClass<T>): Unit =
-    subclassesOf(clazz.serializer())
+@ExperimentalSerializationApi
+public inline fun <Base : Any, reified T : Base> PolymorphicModuleBuilder<Base>.subclassesOfSealed(clazz: KClass<T>): Unit =
+    subclassesOfSealed(clazz.serializer())

docs/polymorphism.md

@@ -415,9 +415,11 @@ fun main() {
 > Note: On Kotlin/Native, you should use `format.encodeToString(PolymorphicSerializer(Project::class), data))` instead due to limited reflection capabilities.
 
 ### Registering sealed children as subclasses
-A sealed parent interface or class can be used to directly register all its children using `subclassesOf`. This will
-expose all children that would be available when serializing the parent directly, but now as sealed. Please note that
-this is will remain open serialization, and the sealed parent serializer will not be used in serialization.
+A sealed parent interface or class can be used to directly register all its children using `subclassesOfSealed`.
+This will expose all children that would be available when serializing the parent directly, but now as sealed. Please
+note that this is will remain open serialization, and the sealed parent serializer will not be used in serialization.
+In addition, it is not valid if the hierarchy contains open (not sealed) polymorphic children (this will result in
+an error at runtime).
 
 <!--- TEST LINES_START -->
 

formats/json-tests/commonTest/src/kotlinx/serialization/features/PolymorphicSealedChildTest.kt

@@ -5,10 +5,10 @@
 package kotlinx.serialization.features
 
 import kotlinx.serialization.*
-import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.*
 import kotlinx.serialization.modules.*
-import kotlinx.serialization.test.assertStringFormAndRestored
-import kotlin.test.Test
+import kotlinx.serialization.test.*
+import kotlin.test.*
 
 class PolymorphicSealedChildTest {
 
@@ -32,14 +32,37 @@ class PolymorphicSealedChildTest {
         data class Baz(val baz: String) : Foo()
     }
 
+    @Serializable
+    sealed class FooOpen: FooBase() {
+        @Serializable
+        data class Bar(val bar: Int) : FooOpen()
+        @Serializable
+        abstract class Baz: FooOpen()
+        @Serializable
+        data class BazChild1(val baz: String) : Baz()
+        @Serializable
+        data class BazChild2(val baz: String) : Baz()
+    }
+
     val sealedModule = SerializersModule {
         polymorphic(FooBase::class) {
-            subclassesOf<Foo>()
+            subclassesOfSealed<Foo>()
         }
     }
 
     val json = Json { serializersModule = sealedModule }
 
+    @Test
+    fun testOpenGrandchildIsInvalid() {
+        assertFailsWith<IllegalArgumentException> {
+            SerializersModule {
+                polymorphic(FooBase::class) {
+                    subclassesOfSealed<FooOpen>()
+                }
+            }
+        }
+    }
+
     @Test
     fun testSaveSealedClassesList() {
         assertStringFormAndRestored(