Adress feedback comments:

- Make it clearer that the hierarchy from the sealed class must only be concrete/sealed. Any open
  descendants fail.
- Revert back to the list of subclasses to be a list, rather than a map.
- Fix some documentation/exception text errors.
- Make the test for open descendants more robust/comprehensive.

Author: pdvrieze

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

@@ -20,20 +20,20 @@ public class PolymorphicModuleBuilder<in Base : Any> @PublishedApi internal cons
     private val baseClass: KClass<Base>,
     private val baseSerializer: KSerializer<Base>? = null
 ) {
-    private val subclasses: MutableMap<KClass<out Base>, KSerializer<out Base>> = mutableMapOf()
+    private val subclasses: MutableList<Pair<KClass<out Base>, KSerializer<out Base>>> = mutableListOf()
     private var defaultSerializerProvider: ((Base) -> SerializationStrategy<Base>?)? = null
     private var defaultDeserializerProvider: ((String?) -> DeserializationStrategy<Base>?)? = null
 
 
     /**
      * 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
+     * the [base class][Base]. Please note that type `T` has to be sealed and have a standard serializer, 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
@@ -75,20 +75,21 @@ public class PolymorphicModuleBuilder<in Base : Any> @PublishedApi internal cons
      * }
      * ```
      *
-     * It is an error if th
+     * Note that if Sub1 is itself open polymorphic this is an error.
+     * 
      */
     @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."
+            "subclassesOfSealed only supports automatic adding of subclasses of sealed types with standard serializers."
         }
         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"
+                "It is not possible to register subclasses (${serializer.descriptor.serialName}) 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.
@@ -100,7 +101,7 @@ public class PolymorphicModuleBuilder<in Base : Any> @PublishedApi internal cons
      * Registers a [subclass] [serializer] in the resulting module under the [base class][Base].
      */
     public fun <T : Base> subclass(subclass: KClass<T>, serializer: KSerializer<T>) {
-        subclasses[subclass] = serializer
+        subclasses.add(subclass to serializer)
     }
 
     /**

docs/polymorphism.md

@@ -419,7 +419,7 @@ A sealed parent interface or class can be used to directly register all its chil
 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).
+an error at runtime). In other words all children/descendants must be either concrete or sealed.
 
 <!--- TEST LINES_START -->
 

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

@@ -15,7 +15,7 @@ class PolymorphicSealedChildTest {
     @Serializable
     data class FooHolder(
         val someMetadata: Int,
-        val payload: List<@Polymorphic FooBase>
+        val payload: List<FooBase>
     )
 
     @Serializable
@@ -29,7 +29,15 @@ class PolymorphicSealedChildTest {
         data class Bar(val bar: Int) : Foo()
         @Serializable
         @SerialName("Baz")
-        data class Baz(val baz: String) : Foo()
+        sealed class Baz : Foo()
+
+        @Serializable
+        @SerialName("BazC1")
+        data class SealedBazChild1(val baz: String): Baz()
+        @Serializable
+        @SerialName("BazC2")
+        data class SealedBazChild2(val baz: String): Baz()
+
     }
 
     @Serializable
@@ -39,8 +47,10 @@ class PolymorphicSealedChildTest {
         @Serializable
         abstract class Baz: FooOpen()
         @Serializable
+        @SerialName("BazOC1")
         data class BazChild1(val baz: String) : Baz()
         @Serializable
+        @SerialName("BazOC2")
         data class BazChild2(val baz: String) : Baz()
     }
 
@@ -52,30 +62,57 @@ class PolymorphicSealedChildTest {
 
     val json = Json { serializersModule = sealedModule }
 
+    /**
+     * Test that attempting to register a grandchild (any descendant of the sealed intermediary)
+     * fails with an exception
+     */
     @Test
     fun testOpenGrandchildIsInvalid() {
-        assertFailsWith<IllegalArgumentException> {
-            SerializersModule {
-                polymorphic(FooBase::class) {
-                    subclassesOfSealed<FooOpen>()
+
+        lateinit var openJson: Json
+        val e = assertFailsWith<IllegalArgumentException> {
+            openJson = Json {
+                serializersModule = SerializersModule {
+                    polymorphic(FooBase::class) {
+                        subclassesOfSealed<FooOpen>()
+                        fail("This code should be unreachable as the previous operation fails")
+                        subclass(FooOpen.BazChild1::class)
+                        subclass(FooOpen.BazChild2::class)
+                    }
                 }
             }
+
+            fail("Unreachable code that would represent the usage if valid (which is isn't per policy)")
+            assertStringFormAndRestored(
+                """{"someMetadata":43,"payload":[{"type":"BazOC1","baz":"aaa"}]}""",
+                FooHolder(43,listOf(FooOpen.BazChild1("aaa"))),
+                FooHolder.serializer(),
+                openJson
+            )
         }
+        assertContains(assertNotNull(e.message), "FooOpen", )
+        assertContains(assertNotNull(e.message), "incomplete hierarchy", )
     }
 
+    /**
+     * This tests both a directly sealed child (Bar) and a (sealed) grandchild (SealedBazChild1)
+     * Nesting sealed hierarchies is valid (and flattened by the plugin).
+     */
     @Test
     fun testSaveSealedClassesList() {
         assertStringFormAndRestored(
             """{"someMetadata":42,"payload":[
             |{"type":"Bar","bar":1},
-            |{"type":"Baz","baz":"2"}]}""".trimMargin().replace("\n", ""),
-            FooHolder(42, listOf(Foo.Bar(1), Foo.Baz("2"))),
+            |{"type":"BazC1","baz":"2"}]}""".trimMargin().replace("\n", ""),
+            FooHolder(42, listOf(Foo.Bar(1), Foo.SealedBazChild1("2"))),
             FooHolder.serializer(),
             json,
-            printResult = true
         )
     }
 
+    /**
+     * Test that a simple direct descendant of the serialized base type can be serialized.
+     */
     @Test
     fun testCanSerializeSealedClassPolymorphicallyOnTopLevel() {
         assertStringFormAndRestored(