Add Dokka documentation

.gitignore

@@ -39,6 +39,7 @@ captures/
 # IntelliJ
 *.iml
 .idea/
+.kotlin/
 
 # Android Studio 3 in .gitignore file.
 .idea/caches

README.md

@@ -21,10 +21,6 @@
 ![badge-support-js-ir]
 ![badge-support-linux-arm]
 
-<!--
-![badge-platform-wasm]
--->
-
 Configurable, streamable, efficient and extensible Encoding/Decoding for Kotlin Multiplatform.
 
 **Base16 (a.k.a. "hex")**
@@ -39,8 +35,6 @@ Configurable, streamable, efficient and extensible Encoding/Decoding for Kotlin
  - Default [RFC 4648 section 4](https://www.ietf.org/rfc/rfc4648.html#section-4)
  - UrlSafe [RFC 4648 section 5](https://www.ietf.org/rfc/rfc4648.html#section-5)
 
-A full list of `kotlin-components` projects can be found [HERE](https://kotlin-components.matthewnelson.io)
-
 ### Usage
 
 **Configure `EncoderDecoder`(s) to your needs**
@@ -56,7 +50,7 @@ val base16 = Base16 {
     // Use lowercase instead of uppercase characters when encoding
     encodeToLowercase = true
 
-    // Use constant-time operations for sensitive data
+    // Use constant-time operations when encoding/decoding sensitive data
     isConstantTime = true
 }
 

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

@@ -77,7 +77,7 @@ fun KmpConfigurationExtension.configureShared(
         mingwAll()
 
         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/encoding/tree/master").toURL()
+            remoteLineSuffix = "#L"
+        }
+
+        documentedVisibilities.set(setOf(
+            Visibility.PUBLIC,
+            Visibility.PROTECTED,
+        ))
+    }
+}

build.gradle.kts

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

gh-pages/publish.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Copyright (c) 2023 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/encoding"' EXIT
+
+cd "$DIR_SCRIPT"
+git clone -b gh-pages --single-branch https://github.com/05nelsonm/encoding.git
+rm -rf "$DIR_SCRIPT/encoding/"*
+echo "encoding.matthewnelson.io" > "$DIR_SCRIPT/encoding/CNAME"
+
+cd ..
+./gradlew clean -DKMP_TARGETS_ALL
+./gradlew dokkaHtmlMultiModule -DKMP_TARGETS_ALL
+cp -aR build/dokka/htmlMultiModule/* gh-pages/encoding
+
+cd "$DIR_SCRIPT/encoding"
+git add --all
+git commit -S --message "Update dokka docs"
+git push

gradle/libs.versions.toml

@@ -1,12 +1,14 @@
 [versions]
 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"
 
 immutable = "0.1.4"
 
 [libraries]
+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" }
@@ -15,4 +17,5 @@ immutable-collections = { module = "io.matthewnelson.immutable:collections", ver
 
 [plugins]
 binary-compat = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "gradle-binary-compat" }
+dokka = { id = "org.jetbrains.dokka", version.ref = "gradle-dokka" }
 multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "gradle-kotlin" }

library/base16/README.md

@@ -0,0 +1,5 @@
+# Module base16
+
+Base16 (a.k.a. "hex") encoding/decoding in accordance with [RFC 4648 section 8][url-rfc]
+
+[url-rfc]: https://www.ietf.org/rfc/rfc4648.html#section-8

library/base32/README.md

@@ -0,0 +1,7 @@
+# Module base32
+
+Base32 encoding/decoding in accordance with [Crockford][url-crockford], [RFC 4648 section 6][url-rfc-6], [RFC 4648 section 6][url-rfc-7]
+
+[url-crockford]: https://www.crockford.com/base32.html
+[url-rfc-6]: https://www.ietf.org/rfc/rfc4648.html#section-6
+[url-rfc-7]: https://www.ietf.org/rfc/rfc4648.html#section-7

library/base32/src/commonMain/kotlin/io/matthewnelson/component/encoding/base32/Base32.kt

@@ -35,6 +35,7 @@ import io.matthewnelson.encoding.core.Encoder.Companion.encodeToCharArray
 import io.matthewnelson.encoding.core.Encoder.Companion.encodeToString
 import kotlin.jvm.JvmOverloads
 
+/** @suppress */
 @Deprecated(
     message = "Replaced by EncoderDecoder. Will be removed in future versions.",
     replaceWith = ReplaceWith(

library/base64/README.md

@@ -0,0 +1,6 @@
+# Module base64
+
+Base64 encoding/decoding in accordance with [RFC 4648 section 4][url-rfc-4], [RFC 4648 section 5][url-rfc-5]
+
+[url-rfc-4]: https://www.ietf.org/rfc/rfc4648.html#section-4
+[url-rfc-5]: https://www.ietf.org/rfc/rfc4648.html#section-5

library/base64/src/commonMain/kotlin/io/matthewnelson/component/base64/Base64.kt

@@ -40,6 +40,7 @@ import io.matthewnelson.encoding.core.Encoder.Companion.encodeToCharArray
 import io.matthewnelson.encoding.core.Encoder.Companion.encodeToString
 import kotlin.jvm.JvmOverloads
 
+/** @suppress */
 @Deprecated(
     message = "Replaced by EncoderDecoder. Will be removed in future versions.",
     replaceWith = ReplaceWith(

library/core/README.md

@@ -0,0 +1,4 @@
+# Module core
+
+Core primitives for encoding/decoding operations, serving as the foundation to other 
+higher level implementations.

library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Decoder.kt

@@ -149,6 +149,7 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
 
         public final override fun close() { isClosed = true }
         public final override fun isClosed(): Boolean = isClosed
+        /** @suppress */
         public final override fun toString(): String = "${this@Decoder}.Decoder.Feed@${hashCode()}"
 
         @Throws(EncodingException::class)
@@ -221,6 +222,7 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
          *
          * @see [decodeToByteArrayOrNull]
          * @throws [EncodingException] if decoding failed.
+         * @suppress
          * */
         @JvmStatic
         @Throws(EncodingException::class)
@@ -231,6 +233,7 @@ public sealed class Decoder<C: EncoderDecoder.Config>(public val config: C) {
             }
         }
 
+        /** @suppress */
         @JvmStatic
         @Deprecated(message = "Should not utilize. Underlying Byte to Char conversion can produce incorrect results")
         public fun ByteArray.decodeToByteArrayOrNull(decoder: Decoder<*>): ByteArray? {

library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/Encoder.kt

@@ -124,6 +124,7 @@ public sealed class Encoder<C: EncoderDecoder.Config>(config: C): Decoder<C>(con
 
         public final override fun close() { isClosed = true }
         public final override fun isClosed(): Boolean = isClosed
+        /** @suppress */
         public final override fun toString(): String = "${this@Encoder}.Encoder.Feed@${hashCode()}"
 
         protected abstract fun consumeProtected(input: Byte)
@@ -199,6 +200,7 @@ public sealed class Encoder<C: EncoderDecoder.Config>(config: C): Decoder<C>(con
          *   data, but is something that can occur with Base16 (hex)
          *   as it produces 2 characters of output for every 1 byte
          *   of input.
+         * @suppress
          * */
         @JvmStatic
         @Throws(EncodingSizeException::class)

library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/EncoderDecoder.kt

@@ -302,28 +302,34 @@ public abstract class EncoderDecoder<C: EncoderDecoder.Config>(config: C): Encod
             @JvmField
             public val name: String = name.trim()
 
+            /** @suppress */
             override fun equals(other: Any?): Boolean {
                 return  other is Setting
                         && other.name == name
             }
 
+            /** @suppress */
             override fun hashCode(): Int {
                 return 17 * 31 + name.hashCode()
             }
 
+            /** @suppress */
             override fun toString(): String = "$name: $value"
         }
 
+        /** @suppress */
         final override fun equals(other: Any?): Boolean {
             return  other is Config
                     && other::class == this::class
                     && other.toString() == toString()
         }
 
+        /** @suppress */
         final override fun hashCode(): Int {
             return 17 * 31 + toString().hashCode()
         }
 
+        /** @suppress */
         final override fun toString(): String {
             return StringBuilder().apply {
                 append("EncoderDecoder.Config [")
@@ -488,20 +494,23 @@ public abstract class EncoderDecoder<C: EncoderDecoder.Config>(config: C): Encod
      * */
     protected abstract fun name(): String
 
+    /** @suppress */
     final override fun equals(other: Any?): Boolean {
         return  other is EncoderDecoder<*>
                 && other::class == this::class
                 && other.name() == name()
                 && other.config.hashCode() == config.hashCode()
     }
 
+    /** @suppress */
     final override fun hashCode(): Int {
         var result = 17
         result = result * 31 + name().hashCode()
         result = result * 31 + config.hashCode()
         return result
     }
 
+    /** @suppress */
     final override fun toString(): String {
         return "EncoderDecoder[${name()}]@${hashCode()}"
     }

library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/internal/InternalEncodingApi.kt

@@ -26,6 +26,8 @@ package io.matthewnelson.encoding.core.internal
  * the following compiler argument:
  *
  *   -Xopt-in=io.matthewnelson.encoding.core.internal.InternalEncodingApi
+ *
+ * @suppress
  * */
 @RequiresOptIn
 @MustBeDocumented

library/core/src/commonMain/kotlin/io/matthewnelson/encoding/core/util/DecoderAction.kt

@@ -27,7 +27,7 @@ import kotlin.jvm.JvmField
 public fun interface DecoderAction {
 
     /**
-     * Convert decoder input character to its bitwise integer
+     * Convert decoder input character to its bitwise integer value.
      * */
     public fun convert(input: Char): Int
 
@@ -49,7 +49,7 @@ public fun interface DecoderAction {
      *
      *     val bits = "48656C6C6F20576F726C6421".map { char ->
      *         parser.parse(char, isConstantTime = true)
-     *             ?: error("Invalid Char[$char])
+     *             ?: error("Invalid Char[$char]")
      *     }
      *
      * @param [action] Pairs of character ranges and their associated [DecoderAction]