Provide documentation for @EncodeDefault and @JsonClassDiscriminator (#1832)

Fixes #1657

Author: sandwwraith

docs/basic-serialization.md

@@ -24,7 +24,7 @@ Once the project is set up, we can start serializing some classes.
   * <a name='optional-property-initializer-call'></a>[Optional property initializer call](basic-serialization.md#optional-property-initializer-call)
   * <a name='required-properties'></a>[Required properties](basic-serialization.md#required-properties)
   * <a name='transient-properties'></a>[Transient properties](basic-serialization.md#transient-properties)
-  * <a name='defaults-are-not-encoded'></a>[Defaults are not encoded](basic-serialization.md#defaults-are-not-encoded)
+  * <a name='defaults-are-not-encoded-by-default'></a>[Defaults are not encoded by default](basic-serialization.md#defaults-are-not-encoded-by-default)
   * <a name='nullable-properties'></a>[Nullable properties](basic-serialization.md#nullable-properties)
   * <a name='type-safety-is-enforced'></a>[Type safety is enforced](basic-serialization.md#type-safety-is-enforced)
   * <a name='referenced-objects'></a>[Referenced objects](basic-serialization.md#referenced-objects)
@@ -115,7 +115,7 @@ Once the project is set up, we can start serializing some classes.
   * <a name='explicit-nulls'></a>[Explicit nulls](json.md#explicit-nulls)
   * <a name='allowing-structured-map-keys'></a>[Allowing structured map keys](json.md#allowing-structured-map-keys)
   * <a name='allowing-special-floating-point-values'></a>[Allowing special floating-point values](json.md#allowing-special-floating-point-values)
-  * <a name='class-discriminator'></a>[Class discriminator](json.md#class-discriminator)
+  * <a name='class-discriminator-for-polymorphism'></a>[Class discriminator for polymorphism](json.md#class-discriminator-for-polymorphism)
 * <a name='json-elements'></a>[Json elements](json.md#json-elements)
   * <a name='parsing-to-json-element'></a>[Parsing to Json element](json.md#parsing-to-json-element)
   * <a name='types-of-json-elements'></a>[Types of Json elements](json.md#types-of-json-elements)

docs/json.md

@@ -4,7 +4,7 @@ package example.exampleBasic02
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
-@Serializable 
+@Serializable
 class Project(val name: String, val language: String)
 
 fun main() {

docs/serialization-guide.md

@@ -4,7 +4,7 @@ package example.exampleBasic03
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
-@Serializable 
+@Serializable
 data class Project(val name: String, val language: String)
 
 fun main() {

guide/example/example-basic-02.kt

@@ -4,15 +4,15 @@ package example.exampleClasses01
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
-@Serializable 
+@Serializable
 class Project(
     // name is a property with backing field -- serialized
     var name: String
 ) {
     var stars: Int = 0 // property with a backing field -- serialized
- 
+
     val path: String // getter only, no backing field -- not serialized
-        get() = "kotlin/$name"                                         
+        get() = "kotlin/$name"
 
     var id by ::name // delegated property -- not serialized
 }

guide/example/example-basic-03.kt

@@ -4,15 +4,15 @@ package example.exampleClasses02
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
-@Serializable 
+@Serializable
 class Project private constructor(val owner: String, val name: String) {
     constructor(path: String) : this(
-        owner = path.substringBefore('/'),    
+        owner = path.substringBefore('/'),
         name = path.substringAfter('/')
-    )                        
+    )
 
     val path: String
-        get() = "$owner/$name"  
+        get() = "$owner/$name"
 }
 
 fun main() {

guide/example/example-classes-01.kt

@@ -4,7 +4,7 @@ package example.exampleClasses04
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
-@Serializable 
+@Serializable
 data class Project(val name: String, val language: String)
 
 fun main() {

guide/example/example-classes-02.kt

@@ -4,7 +4,7 @@ package example.exampleClasses05
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
-@Serializable 
+@Serializable
 data class Project(val name: String, val language: String = "Kotlin")
 
 fun main() {

guide/example/example-classes-04.kt

@@ -9,9 +9,9 @@ fun computeLanguage(): String {
     return "Kotlin"
 }
 
-@Serializable 
+@Serializable
 data class Project(val name: String, val language: String = computeLanguage())
- 
+
 fun main() {
     val data = Json.decodeFromString<Project>("""
         {"name":"kotlinx.serialization","language":"Kotlin"}

guide/example/example-classes-05.kt

@@ -4,7 +4,7 @@ package example.exampleClasses07
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
-@Serializable 
+@Serializable
 data class Project(val name: String, @Required val language: String = "Kotlin")
 
 fun main() {

guide/example/example-classes-06.kt

@@ -4,7 +4,7 @@ package example.exampleClasses08
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
-@Serializable 
+@Serializable
 data class Project(val name: String, @Transient val language: String = "Kotlin")
 
 fun main() {

guide/example/example-classes-07.kt

@@ -4,7 +4,7 @@ package example.exampleClasses09
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
-@Serializable 
+@Serializable
 data class Project(val name: String, val language: String = "Kotlin")
 
 fun main() {

guide/example/example-classes-08.kt

@@ -5,9 +5,21 @@ import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
 @Serializable
-class Project(val name: String, val renamedTo: String? = null)
+data class Project(
+    val name: String,
+    @EncodeDefault val language: String = "Kotlin"
+)
+
+
+@Serializable
+data class User(
+    val name: String,
+    @EncodeDefault(EncodeDefault.Mode.NEVER) val projects: List<Project> = emptyList()
+)
 
 fun main() {
-    val data = Project("kotlinx.serialization")
-    println(Json.encodeToString(data))
+    val userA = User("Alice", listOf(Project("kotlinx.serialization")))
+    val userB = User("Bob")
+    println(Json.encodeToString(userA))
+    println(Json.encodeToString(userB))
 }

guide/example/example-classes-09.kt

@@ -4,12 +4,10 @@ package example.exampleClasses11
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
-@Serializable 
-data class Project(val name: String, val language: String = "Kotlin")
+@Serializable
+class Project(val name: String, val renamedTo: String? = null)
 
 fun main() {
-    val data = Json.decodeFromString<Project>("""
-        {"name":"kotlinx.serialization","language":null}
-    """)
-    println(data)
+    val data = Project("kotlinx.serialization")
+    println(Json.encodeToString(data))
 }

guide/example/example-classes-10.kt

@@ -5,13 +5,11 @@ import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
 @Serializable
-class Project(val name: String, val owner: User)
-
-@Serializable
-class User(val name: String)
+data class Project(val name: String, val language: String = "Kotlin")
 
 fun main() {
-    val owner = User("kotlin")
-    val data = Project("kotlinx.serialization", owner)
-    println(Json.encodeToString(data))
+    val data = Json.decodeFromString<Project>("""
+        {"name":"kotlinx.serialization","language":null}
+    """)
+    println(data)
 }

guide/example/example-classes-11.kt

@@ -5,13 +5,13 @@ import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
 @Serializable
-class Project(val name: String, val owner: User, val maintainer: User)
+class Project(val name: String, val owner: User)
 
 @Serializable
 class User(val name: String)
 
 fun main() {
     val owner = User("kotlin")
-    val data = Project("kotlinx.serialization", owner, owner)
+    val data = Project("kotlinx.serialization", owner)
     println(Json.encodeToString(data))
 }

guide/example/example-classes-12.kt

@@ -5,18 +5,13 @@ import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
 @Serializable
-class Box<T>(val contents: T)
+class Project(val name: String, val owner: User, val maintainer: User)
 
 @Serializable
-data class Project(val name: String, val language: String)
-
-@Serializable
-class Data(
-    val a: Box<Int>,
-    val b: Box<Project>
-)
+class User(val name: String)
 
 fun main() {
-    val data = Data(Box(42), Box(Project("kotlinx.serialization", "Kotlin")))
+    val owner = User("kotlin")
+    val data = Project("kotlinx.serialization", owner, owner)
     println(Json.encodeToString(data))
 }

guide/example/example-classes-13.kt

@@ -5,9 +5,18 @@ import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
 @Serializable
-class Project(val name: String, @SerialName("lang") val language: String)
+class Box<T>(val contents: T)
+
+@Serializable
+data class Project(val name: String, val language: String)
+
+@Serializable
+class Data(
+    val a: Box<Int>,
+    val b: Box<Project>
+)
 
 fun main() {
-    val data = Project("kotlinx.serialization", "Kotlin")
+    val data = Data(Box(42), Box(Project("kotlinx.serialization", "Kotlin")))
     println(Json.encodeToString(data))
 }

guide/example/example-classes-14.kt

@@ -0,0 +1,13 @@
+// This file was automatically generated from basic-serialization.md by Knit tool. Do not edit.
+package example.exampleClasses16
+
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+@Serializable
+class Project(val name: String, @SerialName("lang") val language: String)
+
+fun main() {
+    val data = Project("kotlinx.serialization", "Kotlin")
+    println(Json.encodeToString(data))
+}

guide/example/example-classes-15.kt

@@ -6,10 +6,10 @@ import kotlinx.serialization.json.*
 
 val format = Json { prettyPrint = true }
 
-@Serializable 
+@Serializable
 data class Project(val name: String, val language: String)
 
-fun main() {                                      
+fun main() {
     val data = Project("kotlinx.serialization", "Kotlin")
     println(format.encodeToString(data))
 }

guide/example/example-classes-16.kt

@@ -6,14 +6,14 @@ import kotlinx.serialization.json.*
 
 val format = Json { isLenient = true }
 
-enum class Status { SUPPORTED }                                                     
+enum class Status { SUPPORTED }
 
-@Serializable 
+@Serializable
 data class Project(val name: String, val status: Status, val votes: Int)
-    
-fun main() {             
+
+fun main() {
     val data = format.decodeFromString<Project>("""
-        { 
+        {
             name   : kotlinx.serialization,
             status : SUPPORTED,
             votes  : "9000"

guide/example/example-json-01.kt

@@ -6,10 +6,10 @@ import kotlinx.serialization.json.*
 
 val format = Json { ignoreUnknownKeys = true }
 
-@Serializable 
+@Serializable
 data class Project(val name: String)
-    
-fun main() {             
+
+fun main() {
     val data = format.decodeFromString<Project>("""
         {"name":"kotlinx.serialization","language":"Kotlin"}
     """)

guide/example/example-json-02.kt

@@ -6,7 +6,7 @@ import kotlinx.serialization.json.*
 
 val format = Json { coerceInputValues = true }
 
-@Serializable 
+@Serializable
 data class Project(val name: String, val language: String = "Kotlin")
 
 fun main() {

guide/example/example-json-03.kt

@@ -6,12 +6,12 @@ import kotlinx.serialization.json.*
 
 val format = Json { encodeDefaults = true }
 
-@Serializable 
+@Serializable
 class Project(
-    val name: String, 
+    val name: String,
     val language: String = "Kotlin",
     val website: String? = null
-)           
+)
 
 fun main() {
     val data = Project("kotlinx.serialization")

guide/example/example-json-05.kt

@@ -6,10 +6,10 @@ import kotlinx.serialization.json.*
 
 val format = Json { allowStructuredMapKeys = true }
 
-@Serializable 
+@Serializable
 data class Project(val name: String)
-    
-fun main() {             
+
+fun main() {
     val map = mapOf(
         Project("kotlinx.serialization") to "Serialization",
         Project("kotlinx.coroutines") to "Coroutines"

guide/example/example-json-06.kt

@@ -9,7 +9,7 @@ val format = Json { allowSpecialFloatingPointValues = true }
 @Serializable
 class Data(
     val value: Double
-)                     
+)
 
 fun main() {
     val data = Data(Double.NaN)

guide/example/example-json-08.kt

@@ -10,8 +10,8 @@ val format = Json { classDiscriminator = "#class" }
 sealed class Project {
     abstract val name: String
 }
-            
-@Serializable         
+
+@Serializable
 @SerialName("owned")
 class OwnedProject(override val name: String, val owner: String) : Project()