Update the documentation with example code (and knit).

Author: pdvrieze

docs/polymorphism.md

@@ -19,6 +19,7 @@ In this chapter we'll see how Kotlin Serialization deals with polymorphic class
 * [Open polymorphism](#open-polymorphism)
   * [Registered subclasses](#registered-subclasses)
   * [Serializing interfaces](#serializing-interfaces)
+  * [Registering sealed children as subclasses](#registering-sealed-children-as-subclasses)
   * [Property of an interface type](#property-of-an-interface-type)
   * [Static parent type lookup for polymorphism](#static-parent-type-lookup-for-polymorphism)
   * [Explicitly marking polymorphic class properties](#explicitly-marking-polymorphic-class-properties)
@@ -421,6 +422,60 @@ note that this is will remain open serialization, and the sealed parent serializ
 In addition, it is not valid if the hierarchy contains open (not sealed) polymorphic children (this will result in
 an error at runtime). In other words all children/descendants must be either concrete or sealed.
 
+<!--- TEST -->
+
+<!--- INCLUDE
+import kotlinx.serialization.modules.*
+-->
+
+```kotlin
+interface Base
+
+@Serializable
+sealed interface Sub: Base
+
+@Serializable
+class Sub1(val data: String): Sub
+
+val module1 = SerializersModule {
+  polymorphic(Base::class) {
+     subclassesOfSealed(Sub.serializer())
+  }
+}
+
+val format1 = Json { serializersModule = module1 }
+```
+
+Alternatively the convenience overload allows specifying the sealed type as type parameter.
+
+```kotlin
+val module2 = SerializersModule {
+  polymorphic(Base::class) {
+     subclassesOfSealed<Sub>()
+  }
+}
+
+val format2 = Json { serializersModule = module2 }
+```
+
+Now if we declare `data` with the type of `Base` we can simply call `format.encodeToString` as before.
+```kotlin
+
+fun main() {
+    val data: Base = Sub1("kotlin")
+    println(format1.encodeToString(data))
+    println(format2.encodeToString(data))
+}
+```
+
+```text
+{"type":"example.examplePoly11.Sub1","data":"kotlin"}
+{"type":"example.examplePoly11.Sub1","data":"kotlin"}
+```
+
+> You can get the full code [here](../guide/example/example-poly-11.kt).
+
+
 <!--- TEST LINES_START -->
 
 ### Property of an interface type
@@ -458,7 +513,7 @@ fun main() {
 }        
 ```
 
-> You can get the full code [here](../guide/example/example-poly-11.kt).
+> You can get the full code [here](../guide/example/example-poly-12.kt).
 
 As long as we've registered the actual subtype of the interface that is being serialized in
 the [SerializersModule] of our `format`, we get it working at runtime.
@@ -503,7 +558,7 @@ fun main() {
 }    
 ```
 
-> You can get the full code [here](../guide/example/example-poly-12.kt).
+> You can get the full code [here](../guide/example/example-poly-13.kt).
  
 We get the exception.
 
@@ -551,7 +606,7 @@ fun main() {
 }    
 ```
 
-> You can get the full code [here](../guide/example/example-poly-13.kt).
+> You can get the full code [here](../guide/example/example-poly-14.kt).
 
 However, `Any` is a class and it is not serializable:
 
@@ -593,7 +648,7 @@ fun main() {
 }    
 ```
 
-> You can get the full code [here](../guide/example/example-poly-14.kt).
+> You can get the full code [here](../guide/example/example-poly-15.kt).
 
 With the explicit serializer it works as before.
 
@@ -646,7 +701,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-poly-15.kt).
+> You can get the full code [here](../guide/example/example-poly-16.kt).
  
 <!--- TEST 
 {"project":{"type":"owned","name":"kotlinx.coroutines","owner":"kotlin"}}
@@ -699,7 +754,7 @@ fun main() {
 }        
 -->
 
-> You can get the full code [here](../guide/example/example-poly-16.kt).
+> You can get the full code [here](../guide/example/example-poly-17.kt).
 
 <!--- TEST 
 {"project":{"type":"owned","name":"kotlinx.coroutines","owner":"kotlin"},"any":{"type":"owned","name":"kotlinx.coroutines","owner":"kotlin"}}
@@ -790,7 +845,7 @@ fun main() {
 
 ```
 
-> You can get the full code [here](../guide/example/example-poly-17.kt).
+> You can get the full code [here](../guide/example/example-poly-18.kt).
 
 The JSON that is being produced is deeply polymorphic.
 
@@ -838,7 +893,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-poly-18.kt).
+> You can get the full code [here](../guide/example/example-poly-19.kt).
 
 We get the following exception.
 
@@ -901,7 +956,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-poly-19.kt).
+> You can get the full code [here](../guide/example/example-poly-20.kt).
 
 Notice, how `BasicProject` had also captured the specified type key in its `type` property. 
 
@@ -1005,7 +1060,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-poly-20.kt)
+> You can get the full code [here](../guide/example/example-poly-21.kt)
 
 ```text
 {"type":"Cat","catType":"Tabby"}

docs/serialization-guide.md

@@ -97,6 +97,7 @@ Once the project is set up, we can start serializing some classes.
 * <a name='open-polymorphism'></a>[Open polymorphism](polymorphism.md#open-polymorphism)
   * <a name='registered-subclasses'></a>[Registered subclasses](polymorphism.md#registered-subclasses)
   * <a name='serializing-interfaces'></a>[Serializing interfaces](polymorphism.md#serializing-interfaces)
+  * <a name='registering-sealed-children-as-subclasses'></a>[Registering sealed children as subclasses](polymorphism.md#registering-sealed-children-as-subclasses)
   * <a name='property-of-an-interface-type'></a>[Property of an interface type](polymorphism.md#property-of-an-interface-type)
   * <a name='static-parent-type-lookup-for-polymorphism'></a>[Static parent type lookup for polymorphism](polymorphism.md#static-parent-type-lookup-for-polymorphism)
   * <a name='explicitly-marking-polymorphic-class-properties'></a>[Explicitly marking polymorphic class properties](polymorphism.md#explicitly-marking-polymorphic-class-properties)

guide/example/example-poly-11.kt

@@ -6,26 +6,33 @@ import kotlinx.serialization.json.*
 
 import kotlinx.serialization.modules.*
 
-val module = SerializersModule {
-    polymorphic(Project::class) {
-        subclass(OwnedProject::class)
-    }
+interface Base
+
+@Serializable
+sealed interface Sub: Base
+
+@Serializable
+class Sub1(val data: String): Sub
+
+val module1 = SerializersModule {
+  polymorphic(Base::class) {
+     subclassesOfSealed(Sub.serializer())
+  }
 }
 
-val format = Json { serializersModule = module }
+val format1 = Json { serializersModule = module1 }
 
-interface Project {
-    val name: String
+val module2 = SerializersModule {
+  polymorphic(Base::class) {
+     subclassesOfSealed<Sub>()
+  }
 }
 
-@Serializable
-@SerialName("owned")
-class OwnedProject(override val name: String, val owner: String) : Project
+val format2 = Json { serializersModule = module2 }
 
-@Serializable
-class Data(val project: Project) // Project is an interface
 
 fun main() {
-    val data = Data(OwnedProject("kotlinx.coroutines", "kotlin"))
-    println(format.encodeToString(data))
-}        
+    val data: Base = Sub1("kotlin")
+    println(format1.encodeToString(data))
+    println(format2.encodeToString(data))
+}

guide/example/example-poly-12.kt

@@ -14,16 +14,18 @@ val module = SerializersModule {
 
 val format = Json { serializersModule = module }
 
-@Serializable
-abstract class Project {
-    abstract val name: String
+interface Project {
+    val name: String
 }
-            
+
 @Serializable
 @SerialName("owned")
-class OwnedProject(override val name: String, val owner: String) : Project()
+class OwnedProject(override val name: String, val owner: String) : Project
+
+@Serializable
+class Data(val project: Project) // Project is an interface
 
 fun main() {
-    val data: Any = OwnedProject("kotlinx.coroutines", "kotlin")
+    val data = Data(OwnedProject("kotlinx.coroutines", "kotlin"))
     println(format.encodeToString(data))
-}    
+}        

guide/example/example-poly-13.kt

@@ -7,10 +7,11 @@ import kotlinx.serialization.json.*
 import kotlinx.serialization.modules.*
 
 val module = SerializersModule {
-    polymorphic(Any::class) {
+    polymorphic(Project::class) {
         subclass(OwnedProject::class)
     }
 }
+
 val format = Json { serializersModule = module }
 
 @Serializable

guide/example/example-poly-14.kt

@@ -11,7 +11,6 @@ val module = SerializersModule {
         subclass(OwnedProject::class)
     }
 }
-
 val format = Json { serializersModule = module }
 
 @Serializable
@@ -25,5 +24,5 @@ class OwnedProject(override val name: String, val owner: String) : Project()
 
 fun main() {
     val data: Any = OwnedProject("kotlinx.coroutines", "kotlin")
-    println(format.encodeToString(PolymorphicSerializer(Any::class), data))
+    println(format.encodeToString(data))
 }    

guide/example/example-poly-15.kt

@@ -14,21 +14,16 @@ val module = SerializersModule {
 
 val format = Json { serializersModule = module }
 
-interface Project {
-    val name: String
+@Serializable
+abstract class Project {
+    abstract val name: String
 }
-
+            
 @Serializable
 @SerialName("owned")
-class OwnedProject(override val name: String, val owner: String) : Project
-
-@Serializable
-class Data(
-    @Polymorphic // the code does not compile without it 
-    val project: Any 
-)
+class OwnedProject(override val name: String, val owner: String) : Project()
 
 fun main() {
-    val data = Data(OwnedProject("kotlinx.coroutines", "kotlin"))
-    println(format.encodeToString(data))
-}
+    val data: Any = OwnedProject("kotlinx.coroutines", "kotlin")
+    println(format.encodeToString(PolymorphicSerializer(Any::class), data))
+}    

guide/example/example-poly-16.kt

@@ -5,15 +5,12 @@ import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
 import kotlinx.serialization.modules.*
-import kotlin.reflect.KClass
 
 val module = SerializersModule {
-    fun PolymorphicModuleBuilder<Project>.registerProjectSubclasses() {
+    polymorphic(Any::class) {
         subclass(OwnedProject::class)
     }
-    polymorphic(Any::class) { registerProjectSubclasses() }
-    polymorphic(Project::class) { registerProjectSubclasses() }
-}        
+}
 
 val format = Json { serializersModule = module }
 
@@ -27,12 +24,11 @@ class OwnedProject(override val name: String, val owner: String) : Project
 
 @Serializable
 class Data(
-    val project: Project,
-    @Polymorphic val any: Any 
+    @Polymorphic // the code does not compile without it 
+    val project: Any 
 )
 
 fun main() {
-    val project = OwnedProject("kotlinx.coroutines", "kotlin")
-    val data = Data(project, project)
+    val data = Data(OwnedProject("kotlinx.coroutines", "kotlin"))
     println(format.encodeToString(data))
-}        
+}

guide/example/example-poly-17.kt

@@ -3,46 +3,34 @@ package example.examplePoly17
 
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
-
 import kotlinx.serialization.modules.*
 
-@Serializable
-abstract class Response<out T>
-            
-@Serializable
-@SerialName("OkResponse")
-data class OkResponse<out T>(val data: T) : Response<T>()
-
-val responseModule = SerializersModule {
-    polymorphic(Response::class) {
-        subclass(OkResponse.serializer(PolymorphicSerializer(Any::class)))
-    }
-}
-
-val projectModule = SerializersModule {
+val module = SerializersModule {
     fun PolymorphicModuleBuilder<Project>.registerProjectSubclasses() {
         subclass(OwnedProject::class)
     }
     polymorphic(Any::class) { registerProjectSubclasses() }
     polymorphic(Project::class) { registerProjectSubclasses() }
-}
+}        
 
-@Serializable
-abstract class Project {
-    abstract val name: String
+val format = Json { serializersModule = module }
+
+interface Project {
+    val name: String
 }
-            
+
 @Serializable
-@SerialName("OwnedProject")
-data class OwnedProject(override val name: String, val owner: String) : Project()
+@SerialName("owned")
+class OwnedProject(override val name: String, val owner: String) : Project
 
-val format = Json { serializersModule = projectModule + responseModule }
+@Serializable
+class Data(
+    val project: Project,
+    @Polymorphic val any: Any 
+)
 
 fun main() {
-    // both Response and Project are abstract and their concrete subtypes are being serialized
-    val data: Response<Project> =  OkResponse(OwnedProject("kotlinx.serialization", "kotlin"))
-    val string = format.encodeToString(data)
-    println(string)
-    println(format.decodeFromString<Response<Project>>(string))
-}
-
+    val project = OwnedProject("kotlinx.coroutines", "kotlin")
+    val data = Data(project, project)
+    println(format.encodeToString(data))
+}