Add Dokka documentation

.gitignore

@@ -3,3 +3,7 @@ build/
 *.iml
 .idea/
 local.properties
+.kotlin/
+
+gh-pages/*
+!gh-pages/publish.sh

RELEASING.md

@@ -2,4 +2,9 @@
 
 See [KotlinCrypto/documentation/RELEASING.md][url-kotlincrypto-releasing]
 
+Additionally, publish dokka documentation updates
+```bash
+./gh-pages/publish.sh
+```
+
 [url-kotlincrypto-releasing]: https://github.com/KotlinCrypto/documentation/blob/master/RELEASING.md

build-logic/build.gradle.kts

@@ -18,6 +18,7 @@ plugins {
 }
 
 dependencies {
+    implementation(libs.gradle.dokka)
     implementation(libs.gradle.kmp.configuration)
     implementation(libs.gradle.kotlin)
     implementation(libs.gradle.publish.maven)

build-logic/src/main/kotlin/-KmpConfigurationExtension.kt

@@ -61,7 +61,7 @@ fun KmpConfigurationExtension.configureShared(
         watchosAll()
 
         common {
-            if (publish) pluginIds("publication")
+            if (publish) pluginIds("publication", "dokka")
 
             sourceSetTest {
                 dependencies {

build-logic/src/main/kotlin/dokka.gradle.kts

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2024 Matthew Nelson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ **/
+import org.jetbrains.dokka.DokkaConfiguration.Visibility
+import org.jetbrains.dokka.gradle.DokkaTaskPartial
+import java.net.URI
+
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+tasks.withType<DokkaTaskPartial>().configureEach {
+    suppressInheritedMembers = true
+
+    dokkaSourceSets.configureEach {
+        includes.from("README.md")
+        noStdlibLink = true
+
+        sourceLink {
+            localDirectory = rootDir
+            remoteUrl = URI("https://github.com/05nelsonm/kmp-file/tree/master").toURL()
+            remoteLineSuffix = "#L"
+        }
+
+        documentedVisibilities.set(setOf(
+            Visibility.PUBLIC,
+            Visibility.PROTECTED,
+        ))
+    }
+}

build.gradle.kts

@@ -20,6 +20,7 @@ import org.jetbrains.kotlin.gradle.targets.js.yarn.YarnRootExtension
 plugins {
     alias(libs.plugins.android.library) apply(false)
     alias(libs.plugins.binary.compat)
+    alias(libs.plugins.dokka)
     alias(libs.plugins.kotlin.multiplatform) apply(false)
 }
 

gh-pages/publish.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Copyright (c) 2024 Matthew Nelson
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+set -e
+
+readonly DIR_SCRIPT="$( cd "$( dirname "$0" )" >/dev/null && pwd )"
+
+trap 'rm -rf "$DIR_SCRIPT/kmp-file"' EXIT
+
+cd "$DIR_SCRIPT"
+git clone -b gh-pages --single-branch https://github.com/05nelsonm/kmp-file.git
+rm -rf "$DIR_SCRIPT/kmp-file/"*
+echo "kmp-file.matthewnelson.io" > "$DIR_SCRIPT/kmp-file/CNAME"
+
+cd ..
+./gradlew clean -DKMP_TARGETS_ALL
+./gradlew dokkaHtmlMultiModule -DKMP_TARGETS_ALL
+cp -aR build/dokka/htmlMultiModule/* gh-pages/kmp-file
+
+cd "$DIR_SCRIPT/kmp-file"
+git add --all
+git commit -S --message "Update dokka docs"
+git push

gradle/libs.versions.toml

@@ -4,19 +4,21 @@ androidx-test-runner = "1.5.2"
 
 gradle-android = "8.2.2"
 gradle-binary-compat = "0.16.3"
+gradle-dokka = "1.9.20"
 gradle-kmp-configuration = "0.3.2"
 gradle-kotlin = "1.9.24"
 gradle-publish-maven = "0.29.0"
 
 # tests
-encoding = "2.2.1"
-kotlincrypto-hash = "0.5.1"
+encoding = "2.3.0"
+kotlincrypto-hash = "0.5.3"
 
 [libraries]
 androidx-test-core = { module = "androidx.test:core", version.ref = "androidx-test-core" }
 androidx-test-runner = { module = "androidx.test:runner", version.ref = "androidx-test-runner" }
 
 gradle-android = { module = "com.android.tools.build:gradle", version.ref = "gradle-android" }
+gradle-dokka = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "gradle-dokka" }
 gradle-kmp-configuration = { module = "io.matthewnelson:gradle-kmp-configuration-plugin", version.ref = "gradle-kmp-configuration" }
 gradle-kotlin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "gradle-kotlin" }
 gradle-publish-maven = { module = "com.vanniktech:gradle-maven-publish-plugin", version.ref = "gradle-publish-maven" }
@@ -28,4 +30,5 @@ kotlincrypto-hash-sha2 = { module = "org.kotlincrypto.hash:sha2", version.ref =
 [plugins]
 android-library = { id = "com.android.library", version.ref = "gradle-android" }
 binary-compat = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "gradle-binary-compat" }
+dokka = { id = "org.jetbrains.dokka", version.ref = "gradle-dokka" }
 kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "gradle-kotlin" }

library/file/README.md

@@ -0,0 +1,4 @@
+# Module file
+
+A very simple `File` API for Kotlin Multiplatform. It gets the job done.
+

library/file/src/jsMain/kotlin/io/matthewnelson/kmp/file/Wrappers.kt

@@ -51,6 +51,7 @@ public value class Buffer internal constructor(internal val value: buffer_Buffer
 
     public fun unwrap(): dynamic = value.asDynamic()
 
+    /** @suppress */
     override fun toString(): String = "Buffer@${hashCode()}"
 
     public companion object {
@@ -81,5 +82,6 @@ public value class Stats internal constructor(private val value: fs_Stats) {
 
     public fun unwrap(): dynamic = value.asDynamic()
 
+    /** @suppress */
     override fun toString(): String = "Stats@${hashCode()}"
 }

library/file/src/nonJvmMain/kotlin/io/matthewnelson/kmp/file/File.kt

@@ -100,10 +100,14 @@ public actual class File: Comparable<File> {
         return File(path, direct = null)
     }
 
+    /** @suppress */    
     public override fun compareTo(other: File): Int = realPath.compareTo(other.realPath)
 
+    /** @suppress */    
     public override fun equals(other: Any?): Boolean = other is File && other.realPath == realPath
+    /** @suppress */    
     public override fun hashCode(): Int = realPath.hashCode() xor 1234321
+    /** @suppress */    
     public override fun toString(): String = realPath
 }