Merge remote-tracking branch 'origin/master' into dev

Author: sandwwraith

README.md

@@ -148,7 +148,6 @@ repositories {
 }
 
 dependencies {
-    implementation(kotlin("stdlib", KotlinCompilerVersion.VERSION)) // or "stdlib-jdk8"
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.0.0")
 }
 ```
@@ -162,7 +161,6 @@ repositories {
 }
 
 dependencies {
-    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version" // or "kotlin-stdlib-jdk8"
     implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.0.0"
 }
 ```

docs/json.md

@@ -198,13 +198,13 @@ Project(name=kotlinx.serialization, language=Kotlin)
 
 ### Encoding defaults 
 
-Default values of properties don't have to be encoded, because they will be reconstructed during encoding anyway.
-It can be configured by the [encodeDefaults][JsonBuilder.encodeDefaults] property.
-This is especially useful for nullable properties with null defaults to avoid writing the corresponding 
-null values.
+Default values of properties are not encoded by default, because they will be reconstructed during decoding anyway.
+See [Defaults are not encoded](basic-serialization.md#defaults-are-not-encoded) section for details with example.
+This is especially useful for nullable properties with null defaults and avoids writing the corresponding null values. 
+The default behavior can be changed by the [encodeDefaults][JsonBuilder.encodeDefaults] property.
 
 ```kotlin
-val format = Json { encodeDefaults = false }
+val format = Json { encodeDefaults = true }
 
 @Serializable 
 class Project(
@@ -221,10 +221,10 @@ fun main() {
 
 > You can get the full code [here](../guide/example/example-json-05.kt).
 
-Produces the following output which has only the `name` property:
+It produces the following output which encodes the values of all the properties:
 
 ```text
-{"name":"kotlinx.serialization"}
+{"name":"kotlinx.serialization","language":"Kotlin","website":null}
 ```                 
 
 <!--- TEST -->
@@ -372,7 +372,7 @@ A [JsonElement] class has three direct subtypes, closely following JSON grammar.
 * [JsonObject] represents a JSON `{...}` object. It is a Kotlin [Map] from `String` key to `JsonElement` value.
 
 The `JsonElement` class has `jsonXxx` extensions that cast it to its corresponding subtypes
-([jsonPrimitive], [jsonArray], [jsonObject]). The `JsonPrimitive` class, in turn,
+([jsonPrimitive][_jsonPrimitive], [jsonArray][_jsonArray], [jsonObject][_jsonObject]). The `JsonPrimitive` class, in turn,
 has convenient converters to Kotlin primitive types ([int], [intOrNull], [long], [longOrNull], etc)
 that allow fluent code to work with JSON for which you know the structure of.
 
@@ -916,9 +916,9 @@ The next chapter covers [Alternative and custom formats (experimental)](formats.
 [JsonPrimitive()]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-primitive.html
 [JsonArray]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-array/index.html
 [JsonObject]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-object/index.html
-[jsonPrimitive]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/index.html#kotlinx.serialization.json%2F%2FjsonPrimitive%2Fkotlinx.serialization.json.JsonElement%23%2FPointingToDeclaration%2F
-[jsonArray]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/index.html#kotlinx.serialization.json%2F%2FjsonArray%2Fkotlinx.serialization.json.JsonElement%23%2FPointingToDeclaration%2F
-[jsonObject]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/index.html#kotlinx.serialization.json%2F%2FjsonObject%2Fkotlinx.serialization.json.JsonElement%23%2FPointingToDeclaration%2F
+[_jsonPrimitive]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/index.html#kotlinx.serialization.json%2F%2FjsonPrimitive%2Fkotlinx.serialization.json.JsonElement%23%2FPointingToDeclaration%2F
+[_jsonArray]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/index.html#kotlinx.serialization.json%2F%2FjsonArray%2Fkotlinx.serialization.json.JsonElement%23%2FPointingToDeclaration%2F
+[_jsonObject]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/index.html#kotlinx.serialization.json%2F%2FjsonObject%2Fkotlinx.serialization.json.JsonElement%23%2FPointingToDeclaration%2F
 [int]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-primitive/index.html#kotlinx.serialization.json%2F%2Fint%2Fkotlinx.serialization.json.JsonPrimitive%23%2FPointingToDeclaration%2F
 [intOrNull]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-primitive/index.html#kotlinx.serialization.json%2F%2FintOrNull%2Fkotlinx.serialization.json.JsonPrimitive%23%2FPointingToDeclaration%2F
 [long]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-primitive/index.html#kotlinx.serialization.json%2F%2Flong%2Fkotlinx.serialization.json.JsonPrimitive%23%2FPointingToDeclaration%2F

docs/polymorphism.md

@@ -274,7 +274,7 @@ must be explicitly registered at runtime.
 Let us start with the code from the [Designing serializable hierarchy](#designing-serializable-hierarchy) section.
 To make it work with serialization without making it `sealed`, we have to define a [SerializersModule] using the 
 [SerializersModule {}][SerializersModule()] builder function. In the module the base class is specified 
-in the [polymorphic] builder and each subclass is registered with the [subclass] function. Now, 
+in the [polymorphic][_polymorphic] builder and each subclass is registered with the [subclass] function. Now, 
 a custom JSON configuration can be instantiated with this module and used for serialization.
 
 > Details on custom JSON configurations can be found in 
@@ -875,7 +875,7 @@ The next chapter covers [JSON features](json.md).
 <!--- INDEX kotlinx-serialization-core/kotlinx.serialization.modules -->
 [SerializersModule]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/-serializers-module/index.html
 [SerializersModule()]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/-serializers-module.html
-[polymorphic]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/polymorphic.html
+[_polymorphic]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/polymorphic.html
 [subclass]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/subclass.html
 [plus]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/plus.html
 [SerializersModuleBuilder.include]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/-serializers-module-builder/include.html

docs/serializers.md

@@ -879,7 +879,7 @@ class ProgrammingLanguage(
 To provide a context, we define a [SerializersModule] instance that describes which serializers shall be used 
 at run-time to serialize which contextually-serializable classes. This is done using the 
 [SerializersModule {}][SerializersModule()] builder function, which provides [SerializersModuleBuilder] DSL to 
-register serializers. In the below example we use [contextual] function with the serializer. The corresponding
+register serializers. In the below example we use [contextual][_contextual] function with the serializer. The corresponding
 class this serializer is defined for is fetched automatically via the `reified` type parameter.  
 
 ```kotlin
@@ -1005,7 +1005,6 @@ The next chapter covers [Polymorphism](polymorphism.md).
 [Serializable]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization/-serializable/index.html
 [KSerializer]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization/-k-serializer/index.html
 [KSerializer.descriptor]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization/-k-serializer/index.html#kotlinx.serialization%2FKSerializer%2Fdescriptor%2F%23%2FPointingToDeclaration%2F
-[kotlinx.serialization.serializer]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization/../../../kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization/index.html#kotlinx.serialization%2F%2Fserializer%2F%23%2FPointingToDeclaration%2F
 [SerializationStrategy.serialize]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization/-serialization-strategy/serialize.html
 [SerializationStrategy]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization/-serialization-strategy/index.html
 [DeserializationStrategy.deserialize]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization/-deserialization-strategy/deserialize.html
@@ -1047,7 +1046,7 @@ The next chapter covers [Polymorphism](polymorphism.md).
 [SerializersModule]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/-serializers-module/index.html
 [SerializersModule()]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/-serializers-module.html
 [SerializersModuleBuilder]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/-serializers-module-builder/index.html
-[contextual]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/contextual.html
+[_contextual]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-core/kotlinx-serialization-core/kotlinx.serialization.modules/contextual.html
 <!--- MODULE /kotlinx-serialization-json -->
 <!--- INDEX kotlinx-serialization-json/kotlinx.serialization.json -->
 [Json]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json/index.html

formats/README.md

@@ -77,6 +77,15 @@ not be available in other formats such as JSON.
 
 Allows serialization and deserialization of objects to and from [YAML](http://yaml.org).
 
+### YAML (Multiplatform)
+
+* GitHub repo: [him188/yamlkt](https://github.com/him188/yamlkt)
+* Artifact ID: `net.mamoe.yamlkt:yamlkt`
+* Platform: all supported platforms
+
+Allows serialization and deserialization of objects to and from [YAML](http://yaml.org). 
+Basic serial operations have been implemented, but some features such as compound keys and polymorphism are still work in progress.
+
 ### CBOR
 
 * GitHub repo: [L-Briand/obor](https://github.com/L-Briand/obor)

gradle.properties

@@ -16,7 +16,7 @@ jackson_version=2.10.0.pr1
 dokka_version=1.4.20-multimodule-dev-7
 native.deploy=
 validator_version=0.2.3
-knit_version=0.2.1
+knit_version=0.2.2
 coroutines_version=1.3.9
 
 kotlin.mpp.enableGranularSourceSetsMetadata=true

guide/example/example-json-05.kt

@@ -4,7 +4,7 @@ package example.exampleJson05
 import kotlinx.serialization.*
 import kotlinx.serialization.json.*
 
-val format = Json { encodeDefaults = false }
+val format = Json { encodeDefaults = true }
 
 @Serializable 
 class Project(

guide/test/JsonTest.kt

@@ -39,7 +39,7 @@ class JsonTest {
     @Test
     fun testExampleJson05() {
         captureOutput("ExampleJson05") { example.exampleJson05.main() }.verifyOutputLines(
-            "{\"name\":\"kotlinx.serialization\"}"
+            "{\"name\":\"kotlinx.serialization\",\"language\":\"Kotlin\",\"website\":null}"
         )
     }