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

7 files changed, 25 insertions, 8 deletions

diff --git a/RELEASING.md b/RELEASING.md
index b4ec188f..fe4d7b1a 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -41,9 +41,10 @@ If review is not required, commit directly to `dev`.
    * Close the repository and wait for it to verify.
    * Release it.
    
-5. Update documentation website:<br>
-    * Set new value for [`kotlinx.serialization.release.tag`](https://buildserver.labs.intellij.net/admin/editProject.html?projectId=Kotlin_KotlinSites_Builds_KotlinlangOrg_LibrariesAPIs&tab=projectParams)
-    * And run deploy [configuration](https://buildserver.labs.intellij.net/buildConfiguration/Kotlin_KotlinSites_Builds_KotlinlangOrg_KotlinSerializationApi?branch=%3Cdefault%3E&mode=builds)
+5. Propose the website documentation update:<br>
+    * Set a new value for [`KOTLINX_SERIALIZATION_RELEASE_TAG`](https://github.com/JetBrains/kotlin-web-site/blob/master/.teamcity/BuildParams.kt), creating a pull request in the website's repository.
+    * The website team will be notified about the pull request, review your changes, and merge it to master after all checks pass.
+    * Once the pull request is merged to the main branch, it automatically will trigger the website's update, which will be done within an hour.   
 
 6. Create a new release in [Github releases](https://github.com/Kotlin/kotlinx.serialization/releases). Use created git tag for title and changelog message for body.
 
diff --git a/build.gradle b/build.gradle
index 236943b8..0d21932a 100644
--- a/build.gradle
+++ b/build.gradle
@@ -188,3 +188,7 @@ subprojects {
 apply from: rootProject.file('gradle/compiler-version.gradle')
 apply from: rootProject.file("gradle/dokka.gradle")
 apply from: rootProject.file("gradle/benchmark-parsing.gradle")
+
+tasks.named("dokkaHtmlMultiModule") {
+    pluginsMapConfiguration.set(["org.jetbrains.dokka.base.DokkaBase": """{ "templatesDir": "${projectDir.toString().replace('\\', '/')}/dokka-templates" }"""])
+}
diff --git a/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptor.kt b/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptor.kt
index af719307..27dd27da 100644
--- a/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptor.kt
+++ b/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptor.kt
@@ -116,7 +116,7 @@ import kotlinx.serialization.encoding.*
  * SerialDescriptor("my.package.Data") {
  *     // intField is deliberately ignored by serializer -- not present in the descriptor as well
  *     element<Long>("_longField") // longField is named as _longField
- *     element("stringField", listDescriptor<String>())
+ *     element("stringField", listSerialDescriptor<String>())
  * }
  * ```
  *
diff --git a/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptors.kt b/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptors.kt
index f9e51737..a461ca6f 100644
--- a/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptors.kt
+++ b/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptors.kt
@@ -27,8 +27,8 @@ import kotlin.reflect.*
  * SerialDescriptor("my.package.Data") {
  *     // intField is deliberately ignored by serializer -- not present in the descriptor as well
  *     element<Long>("_longField") // longField is named as _longField
- *     element("stringField", listDescriptor<String>())
- *     element("nullableInt", descriptor<Int>().nullable)
+ *     element("stringField", listSerialDescriptor<String>())
+ *     element("nullableInt", serialDescriptor<Int>().nullable)
  * }
  * ```
  *
diff --git a/dokka-templates/README.md b/dokka-templates/README.md
new file mode 100644
index 00000000..2b16f5bf
--- /dev/null
+++ b/dokka-templates/README.md
@@ -0,0 +1,12 @@
+# Dokka's template customization
+To provide unified navigation for all parts of [kotlinlang.org](https://kotlinlang.org/),
+the Kotlin Website Team uses this directory to place custom templates in this folder
+during the website build time on TeamCity.
+
+It is not practical to place these templates in the kotlinx.serialization repository because they change from time to time
+and aren't related to the library's release cycle.
+
+The folder is defined as a source for custom templates by the templatesDir property through Dokka's plugin configuration.
+
+[Here](https://kotlin.github.io/dokka/1.7.20-SNAPSHOT/user_guide/output-formats/html/#custom-html-pages), you can
+find more about the customization of Dokka's HTML output.
\ No newline at end of file
diff --git a/formats/json-okio/commonMain/src/kotlinx/serialization/json/okio/OkioStreams.kt b/formats/json-okio/commonMain/src/kotlinx/serialization/json/okio/OkioStreams.kt
index 47d2072d..34d27637 100644
--- a/formats/json-okio/commonMain/src/kotlinx/serialization/json/okio/OkioStreams.kt
+++ b/formats/json-okio/commonMain/src/kotlinx/serialization/json/okio/OkioStreams.kt
@@ -38,8 +38,6 @@ public fun <T> Json.encodeToBufferedSink(
 /**
  * Serializes given [value] to a [target] using UTF-8 encoding and serializer retrieved from the reified type parameter.
  *
- * If [target] is not a [BufferedSink] then called [Sink.buffer] for it to create buffered wrapper.
- *
  * @throws [SerializationException] if the given value cannot be serialized to JSON.
  * @throws [okio.IOException] If an I/O error occurs and sink can't be written to.
  */
diff --git a/gradle/dokka.gradle b/gradle/dokka.gradle
index 157ab82e..bccf4fd7 100644
--- a/gradle/dokka.gradle
+++ b/gradle/dokka.gradle
@@ -20,6 +20,8 @@ subprojects {
 
     tasks.named('dokkaHtmlPartial') {
         outputDirectory = file("build/dokka")
+        pluginsMapConfiguration.set(["org.jetbrains.dokka.base.DokkaBase": """{ "templatesDir": "${rootProject.projectDir.toString().replace('\\', '/')}/dokka-templates" }"""])
+
         dokkaSourceSets {
             configureEach {
                 includes.from(rootProject.file('dokka/moduledoc.md').path)