Merge branch 'master' into develop

Author: fzhinkin

README.md

@@ -11,22 +11,22 @@
 A multiplatform Kotlin library providing basic IO primitives. `kotlinx-io` is based on [Okio](https://github.com/square/okio) but does not preserve backward compatibility with it.
 
 ## Overview
-The library is built around `Buffer` - a mutable sequence of bytes. `Buffer` works like a queue allowing one to read data from its head or write data to its tail.
+**kotlinx-io** is built around `Buffer` - a mutable sequence of bytes.
 
-`Buffer` provides functions to read and write data of different built-in types and copy data to or from other buffers. Depending on a target platform, extension functions allowing data exchange with platform-specific types are also provided.
+`Buffer` works like a queue, allowing to read data from its head or to write data to its tail.
+`Buffer` provides functions to read and write data of different built-in types, and to copy data to or from other `Buffer`s.
+Depending on the target platform, extension functions allowing data exchange with platform-specific types are also available.
 
-`Buffer` consists of segments organized as a linked list. Segments allow reducing memory allocations during the buffer's expansion and copying. The latter is achieved by delegating or sharing the ownership over the underlying buffer's segments with other buffers.
+A `Buffer` consists of segments organized as a linked list: segments allow reducing memory allocations during the buffer's expansion and copy,
+with the latter achieved by delegating or sharing the ownership over the underlying buffer's segments with other buffers.
 
-The library also provides interfaces representing data sources and destinations - `Source` and `Sink`.
+**kotlinx-io** provides interfaces representing data sources and destinations - `Source` and `Sink`,
+and in addition to the *mutable* `Buffer` the library also provides an *immutable* sequence of bytes - `ByteString`.
 
-In addition to `Buffer`, the library provides an immutable sequence of bytes - `ByteString`.
+An experimental filesystem support is shipped under the `kotlinx.io.files` package,
+which includes the `FileSystem` interface and its default implementation - `SystemFileSystem`.
 
-Also, there's an experimental filesystem support provided by `kotlinx.io.files` package. 
-The package includes `FileSystem` interface and its implementation - `SystemFileSystem`. 
-
-`FileSystem` provides basic operations for working with files and directories.
-
-File and directory paths are represented by yet another class provided by the package - `Path`.
+`FileSystem` provides basic operations for working with files and directories, which are represented by yet another class under the same package - `Path`.
 
 There are two `kotlinx-io` modules:
 - [kotlinx-io-bytestring](./bytestring) - provides `ByteString`.

build-logic/build.gradle.kts

@@ -13,6 +13,7 @@ repositories {
 
 dependencies {
     implementation(libs.kotlin.gradle.plugin)
+    implementation(libs.dokka.gradle.plugin)
     implementation(libs.animalsniffer.gradle.plugin)
 }
 

build-logic/src/main/kotlin/kotlinx/io/conventions/kotlinx-io-dokka.gradle.kts

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2017-2023 JetBrains s.r.o. and respective authors and developers.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENCE file.
+ */
+
+import org.jetbrains.dokka.gradle.*
+import java.net.*
+
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+tasks.withType<DokkaTaskPartial>().configureEach {
+    dokkaSourceSets.configureEach {
+        includes.from("Module.md")
+
+        if (name.endsWith("Main")) {
+            sourceLink {
+                // sources are located in projectDir/PLATFORM/src
+                // where the PLATFORM could be jvm, js, darwin, etc.
+                // configuration happens in kotlinx-io-multiplatform.gradle.kts:KotlinSourceSet.configureSourceSet
+                val platform = name.dropLast(4)
+                val relPath = rootProject.projectDir.toPath().relativize(projectDir.toPath())
+                localDirectory.set(projectDir.resolve("$platform/src"))
+                remoteUrl.set(URL("https://github.com/kotlin/kotlinx-io/tree/master/$relPath/$platform/src"))
+                remoteLineSuffix.set("#L")
+            }
+        }
+    }
+}

bytestring/build.gradle.kts

@@ -3,9 +3,9 @@ import org.jetbrains.dokka.gradle.DokkaTaskPartial
 plugins {
     id("kotlinx-io-multiplatform")
     id("kotlinx-io-publish")
+    id("kotlinx-io-dokka")
     id("kotlinx-io-android-compat")
     alias(libs.plugins.kover)
-    alias(libs.plugins.dokka)
 }
 
 kotlin {
@@ -30,8 +30,6 @@ kotlin {
 
 tasks.withType<DokkaTaskPartial>().configureEach {
     dokkaSourceSets.configureEach {
-        includes.from("Module.md")
-
         perPackageOption {
             suppress.set(true)
             matchingRegex.set(".*unsafe.*")

core/build.gradle.kts

@@ -9,9 +9,9 @@ import org.jetbrains.kotlin.gradle.targets.js.dsl.KotlinTargetWithNodeJsDsl
 plugins {
     id("kotlinx-io-multiplatform")
     id("kotlinx-io-publish")
+    id("kotlinx-io-dokka")
     id("kotlinx-io-android-compat")
     alias(libs.plugins.kover)
-    alias(libs.plugins.dokka)
 }
 
 kotlin {
@@ -69,8 +69,6 @@ kotlin {
 
 tasks.withType<DokkaTaskPartial>().configureEach {
     dokkaSourceSets.configureEach {
-        includes.from("Module.md")
-
         samples.from(
             "common/test/samples/rawSinkSample.kt",
             "common/test/samples/rawSourceSample.kt",

gradle/libs.versions.toml

@@ -13,6 +13,7 @@ animalsniffer = "1.7.1"
 
 kotlinx-benchmark-runtime = { group = "org.jetbrains.kotlinx", name = "kotlinx-benchmark-runtime", version.ref = "benchmark" }
 kotlin-gradle-plugin = { group = "org.jetbrains.kotlin", name = "kotlin-gradle-plugin", version.ref = "kotlin" }
+dokka-gradle-plugin = { group = "org.jetbrains.dokka", name = "dokka-gradle-plugin", version.ref = "dokka" }
 kotlinx-coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "coroutines" }
 animalsniffer-gradle-plugin = { group = "ru.vyarus", name = "gradle-animalsniffer-plugin", version.ref = "animalsniffer" }