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

Author: sandwwraith

CONTRIBUTING.md

@@ -22,7 +22,7 @@ Submit issues [here](https://github.com/Kotlin/kotlinx.serialization/issues).
   * Use a 'feature request' template when creating a new issue.
   * Explain why you need the feature — what's your use-case, what's your domain.
   * Explaining the problem you face is more important than suggesting a solution. 
-    Report your problem even if you don't have any proposed solution.
+    Even if you don't have a proposed solution, please report your problem.
   * If there is an alternative way to do what you need, then show the code of the alternative.
 
 ## Submitting PRs
@@ -40,7 +40,7 @@ so do familiarize yourself with the following guidelines.
 * If you fix documentation:
   * After fixing/changing code examples in the [`docs`](docs) folder or updating any references in the markdown files
     run the [Knit tool](#running-the-knit-tool) and commit the resulting changes as well. 
-    It will not pass the tests otherwise.
+    Your changes will not pass the tests otherwise.
   * If you plan extensive rewrites/additions to the docs, then please [contact the maintainers](#contacting-maintainers)
     to coordinate the work in advance.    
 * If you make any code changes:
@@ -49,7 +49,7 @@ so do familiarize yourself with the following guidelines.
     * Use imports with '*'.
   * [Build the project](#building) to make sure it all works and passes the tests.
 * If you fix a bug:
-  * Write the test the reproduces the bug.
+  * Write the test that reproduces the bug.
   * Fixes without tests are accepted only in exceptional circumstances if it can be shown that writing the 
     corresponding test is too hard or otherwise impractical.
   * Follow the style of writing tests that is used in this project: 
@@ -69,7 +69,7 @@ so do familiarize yourself with the following guidelines.
   * You can submit a PR to the [list of community-supported formats](formats/README.md#other-community-supported-formats) 
     with a description of your library.
 * Comment on the existing issue if you want to work on it. Ensure that the issue not only describes a problem,
-  but also describes a solution that had received a positive feedback. Propose a solution if there isn't any.
+  but also describes a solution that has received positive feedback. Propose a solution if there isn't any.
 
 ## Building
 

docs/value-classes.md

@@ -98,7 +98,7 @@ in `serialize` method:
 
 ```kotlin
 override fun serialize(encoder: Encoder, value: NamedColor) {
-  encoder.beginStructure(descriptor) {
+  encoder.encodeStructure(descriptor) {
     encodeSerializableElement(descriptor, 0, Color.serializer(), value.color)
     encodeStringElement(descriptor, 1, value.name)
   }
@@ -113,7 +113,7 @@ unboxed value:
 
 ```kotlin
 override fun serialize(encoder: Encoder, value: NamedColor) {
-  encoder.beginStructure(descriptor) {
+  encoder.encodeStructure(descriptor) {
     encodeInlineElement(descriptor, 0).encodeInt(value.color)
     encodeStringElement(descriptor, 1, value.name)
   }
@@ -123,7 +123,7 @@ override fun serialize(encoder: Encoder, value: NamedColor) {
 The same principle goes also with [CompositeDecoder]: it has [decodeInlineElement][CompositeDecoder.decodeInlineElement] function that returns [Decoder].
 
 If your class should be represented as a primitive (as shown in [Primitive serializer](serializers.md#primitive-serializer) section),
-and you cannot use [beginStructure][Encoder.beginStructure] function, there is a complementary function in [Encoder] called [encodeInline][Encoder.encodeInline].
+and you cannot use [encodeStructure][Encoder.encodeStructure] function, there is a complementary function in [Encoder] called [encodeInline][Encoder.encodeInline].
 We will use it to show an example how one can represent a class as an unsigned integer.
 
 Let's start with a UID class:
@@ -187,7 +187,7 @@ override fun deserialize(decoder: Decoder): UID {
 [CompositeDecoder]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.encoding/-composite-decoder/index.html
 [CompositeDecoder.decodeInlineElement]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.encoding/-composite-decoder/decode-inline-element.html
 [Decoder]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.encoding/-decoder/index.html
-[Encoder.beginStructure]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.encoding/-encoder/begin-structure.html
+[Encoder.encodeStructure]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.encoding/encode-structure.html
 [Encoder.encodeInline]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.encoding/-encoder/encode-inline.html
 [Encoder.encodeInt]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.encoding/-encoder/encode-int.html
 

dokka/moduledoc.md

@@ -5,6 +5,10 @@ format implementation.
 # Module kotlinx-serialization-json
 Stable and ready to use JSON format implementation, `JsonElement` API to operate with JSON trees and JSON-specific serializers.
 
+# Module kotlinx-serialization-json-okio
+Extensions for kotlinx.serialization.json.Json for integration with the popular [Okio](https://square.github.io/okio/) library.
+Currently experimental.
+
 # Module kotlinx-serialization-cbor
 Concise Binary Object Representation (CBOR) format implementation, as per [RFC 7049](https://tools.ietf.org/html/rfc7049).
 
@@ -17,7 +21,7 @@ You can learn about "Human-Optimized Config Object Notation" or HOCON from libra
 Allows converting arbitrary hierarchy of Kotlin classes to a flat key-value structure à la Java Properties.
 
 # Module kotlinx-serialization-protobuf
-Protocol buffers serialization format implementation, mostly compliant to [proto2](https://developers.google.com/protocol-buffers/docs/proto) specification.
+[Protocol buffers](https://protobuf.dev/) serialization format implementation.
 
 # Package kotlinx.serialization
 Basic core concepts and annotations that set up serialization process.
@@ -42,8 +46,14 @@ HOCON serialization format implementation for converting Kotlin classes from and
 JSON serialization format implementation, JSON tree data structures with builders for them,
 and JSON-specific serializers.
 
+# Package kotlinx.serialization.json.okio
+Extensions for kotlinx.serialization.json.Json for integration with the popular [Okio](https://square.github.io/okio/) library.
+
 # Package kotlinx.serialization.protobuf
-Protocol buffers serialization format implementation, mostly compliant to [proto2](https://developers.google.com/protocol-buffers/docs/proto) specification. 
+[Protocol buffers](https://protobuf.dev/) serialization format implementation.
+
+# Package kotlinx.serialization.protobuf.schema
+Experimental generator of ProtoBuf schema from Kotlin classes.
 
 # Package kotlinx.serialization.properties
 Properties serialization format implementation that represents the input data as a plain map of properties.

formats/README.md

@@ -5,13 +5,14 @@ were not included in the core library.
 
 For convenience, they have same `groupId`, versioning and release cycle as core library.
 
-| Format     | Artifact id                        | Platform                | Status       | Notes                                                                                                                                                                                                                                                                                                        |
-|------------|------------------------------------|-------------------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| JSON       | `kotlinx-serialization-json`       | all supported platforms | stable       |
-| HOCON      | `kotlinx-serialization-hocon`      | JVM only                | experimental | Allows deserialization of `Config` object from popular [lightbend/config](https://github.com/lightbend/config) library into Kotlin objects.You can learn about "Human-Optimized Config Object Notation" or HOCON from library's [readme](https://github.com/lightbend/config#using-hocon-the-json-superset). |
-| ProtoBuf   | `kotlinx-serialization-protobuf`   | all supported platforms | experimental |
-| CBOR       | `kotlinx-serialization-cbor`       | all supported platforms | experimental |
-| Properties | `kotlinx-serialization-properties` | all supported platforms | experimental | Allows converting arbitrary hierarchy of Kotlin classes to a flat key-value structure à la Java Properties.                                                                                                                                                                                                  |
+| Format     | Artifact id                        | Platform                        | Status       | Notes                                                                                                                                                                                                                                                                                                        |
+|------------|------------------------------------|---------------------------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| JSON       | `kotlinx-serialization-json`       | all supported platforms         | stable       |                                                                                                                                                                                                                                                                                                              |
+| JSON-Okio  | `kotlinx-serialization-json-okio`  | all supported by Okio platforms | experimental | Extensions on Json for integration with [Okio](https://square.github.io/okio/) library.                                                                                                                                                                                                                      |
+| HOCON      | `kotlinx-serialization-hocon`      | JVM only                        | experimental | Allows deserialization of `Config` object from popular [lightbend/config](https://github.com/lightbend/config) library into Kotlin objects.You can learn about "Human-Optimized Config Object Notation" or HOCON from library's [readme](https://github.com/lightbend/config#using-hocon-the-json-superset). |
+| ProtoBuf   | `kotlinx-serialization-protobuf`   | all supported platforms         | experimental |                                                                                                                                                                                                                                                                                                              |
+| CBOR       | `kotlinx-serialization-cbor`       | all supported platforms         | experimental |                                                                                                                                                                                                                                                                                                              |
+| Properties | `kotlinx-serialization-properties` | all supported platforms         | experimental | Allows converting arbitrary hierarchy of Kotlin classes to a flat key-value structure à la Java Properties.                                                                                                                                                                                                  |
 
 ## Other community-supported formats
 

formats/json-okio/build.gradle.kts

@@ -2,6 +2,8 @@
  * Copyright 2017-2022 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 import Java9Modularity.configureJava9ModuleInfo
+import org.jetbrains.dokka.gradle.*
+import java.net.*
 
 plugins {
     kotlin("multiplatform")
@@ -29,3 +31,16 @@ kotlin {
 }
 
 project.configureJava9ModuleInfo()
+
+tasks.named<DokkaTaskPartial>("dokkaHtmlPartial") {
+    dokkaSourceSets {
+        configureEach {
+            externalDocumentationLink {
+                url.set(URL("https://square.github.io/okio/3.x/okio/"))
+                packageListUrl.set(
+                    file("dokka/okio.package.list").toURI().toURL()
+                )
+            }
+        }
+    }
+}