Add dokka documentation at https://hash.kotlincrypto.org

.gitignore

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

README.md

@@ -3,8 +3,8 @@
 [![badge-latest-release]][url-latest-release]
 
 [![badge-kotlin]][url-kotlin]
-[![badge-core]][url-core]
 [![badge-bitops]][url-bitops]
+[![badge-core]][url-core]
 [![badge-sponges]][url-sponges]
 
 ![badge-platform-android]
@@ -25,90 +25,17 @@
 
 Cryptographic hash functions for Kotlin Multiplatform
 
-Utilized by [KotlinCrypto/MACs][url-macs]
-
-### Usage
-
-See [HERE][url-core-usage] for basic usage example for `Digest`.
-
-```kotlin
-fun main() {
-    // Digests that may be needed for backward compatibility but 
-    // should no longer be utilized because they have been broken.
-    MD5()
-    SHA1()
-}
-```
-
-`SHA2 Digests`
-
-```kotlin
-fun main() {
-    SHA224()
-    SHA256()
-    SHA384()
-    SHA512()
-
-    SHA512t(t = 224) // SHA-512/224
-    SHA512t(t = 256) // SHA-512/256
-}
-```
-
-`SHA3 Digests`
+### Modules
 
-```kotlin
-fun main() {
-    Keccak224()
-    Keccak256()
-    Keccak384()
-    Keccak512()
-    SHA3_224()
-    SHA3_256()
-    SHA3_384()
-    SHA3_512()
-
-    SHAKE128()
-    SHAKE256(outputLength = 640) // returns 640 bytes instead of the default when digest() is invoked
-
-    // NIST.SP.800-185 derived functions
-    val S = "My Customization".encodeToByteArray()
-    CSHAKE128(null, S, outputLength = 128)
-    CSHAKE256(null, S)
-    ParallelHash128(null, B = 123)
-    ParallelHash256(S, B = 456, outputLength = 123)
-    TupleHash128(S, outputLength = 320)
-    TupleHash256(null)
-}
-```
-
-`SHA3 XOFs` (i.e. [Extendable-Output Functions][url-pub-xof])
-
-See [HERE][url-core-usage] for details on what `XOFs` are, and a basic usage example for `Xof`.
-
-```kotlin
-fun main() {
-    SHAKE128.xOf()
-    SHAKE256.xOf()
-
-    // NIST.SP.800-185 derived functions
-    val S = "My Customization".encodeToByteArray()
-    CSHAKE128.xOf(null, S)
-    CSHAKE256.xOf(null, S)
-    ParallelHash128.xOf(S, B = 123)
-    ParallelHash256.xOf(B = 654)
-    TupleHash128.xOf(S)
-    TupleHash256.xOf()
-}
-```
+ - [md](library/md/README.md)
+ - [sha1](library/sha1/README.md)
+ - [sha2](library/sha2/README.md)
+ - [sha3](library/sha3/README.md)
+ - [blake2](library/blake2/README.md)
 
-`BLAKE2 Digests`
+### API Docs
 
-```kotlin
-fun main() {
-    BLAKE2b(512)
-    BLAKE2s(256)
-}
-```
+ - [hash.kotlincrypto.org][url-docs]
 
 ### Get Started
 
@@ -143,6 +70,9 @@ dependencies {
     // ParallelHash128, ParallelHash256
     // TupleHash128, TupleHash256
     implementation("org.kotlincrypto.hash:sha3")
+
+    // BLAKE2b, BLAKE2s
+    implementation("org.kotlincrypto.hash:blake2")
 }
 ```
 
@@ -179,8 +109,6 @@ dependencies {
 [url-kotlin]: https://kotlinlang.org
 [url-bitops]: https://github.com/KotlinCrypto/bitops
 [url-core]: https://github.com/KotlinCrypto/core
-[url-core-usage]: https://github.com/KotlinCrypto/core#usage
 [url-sponges]: https://github.com/KotlinCrypto/sponges
-[url-macs]: https://github.com/KotlinCrypto/MACs
 [url-version-catalog]: https://github.com/KotlinCrypto/version-catalog
-[url-pub-xof]: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf
+[url-docs]: https://hash.kotlincrypto.org

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

@@ -25,10 +25,9 @@ fun KmpConfigurationExtension.configureShared(
     publish: Boolean = false,
     action: Action<KmpConfigurationContainerDsl>
 ) {
-//    TODO: Enable once module :library:md5 is removed
-//    if (publish) {
-//        require(!java9ModuleName.isNullOrBlank()) { "publications must specify a module-info name" }
-//    }
+    if (publish) {
+        require(!java9ModuleName.isNullOrBlank()) { "publications must specify a module-info name" }
+    }
 
     configure {
         options {
@@ -76,7 +75,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,45 @@
+/*
+ * Copyright (c) 2025 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
+
+        externalDocumentationLink {
+            url = URI("https://core.kotlincrypto.org/").toURL()
+        }
+
+        sourceLink {
+            localDirectory = rootDir
+            remoteUrl = URI("https://github.com/KotlinCrypto/hash/tree/master").toURL()
+            remoteLineSuffix = "#L"
+        }
+
+        documentedVisibilities.set(setOf(
+            Visibility.PUBLIC,
+        ))
+    }
+}

build.gradle.kts

@@ -21,6 +21,7 @@ plugins {
     alias(libs.plugins.android.library) apply(false)
     alias(libs.plugins.benchmark) 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,37 @@
+#!/usr/bin/env bash
+# Copyright (c) 2025 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 )"
+readonly REPO_NAME="hash"
+
+trap 'rm -rf "$DIR_SCRIPT/$REPO_NAME"' EXIT
+
+cd "$DIR_SCRIPT"
+git clone -b gh-pages --single-branch https://github.com/KotlinCrypto/$REPO_NAME.git
+rm -rf "$DIR_SCRIPT/$REPO_NAME/"*
+echo "$REPO_NAME.kotlincrypto.org" > "$DIR_SCRIPT/$REPO_NAME/CNAME"
+
+cd ..
+./gradlew clean -DKMP_TARGETS_ALL
+./gradlew dokkaHtmlMultiModule --no-build-cache -DKMP_TARGETS_ALL
+cp -aR build/dokka/htmlMultiModule/* gh-pages/$REPO_NAME
+
+cd "$DIR_SCRIPT/$REPO_NAME"
+sed -i "s|module:|module:library/|g" "package-list"
+
+git add --all
+git commit -S --message "Update dokka docs"
+git push

gradle/libs.versions.toml

@@ -8,6 +8,7 @@ encoding                    = "2.3.1"
 gradle-android              = "8.2.2"
 gradle-benchmark            = "0.4.11"
 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"
@@ -17,6 +18,7 @@ kotlincrypto-core           = "0.6.1-SNAPSHOT"
 kotlincrypto-sponges        = "0.3.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" }
@@ -38,4 +40,5 @@ encoding-base64             = { module = "io.matthewnelson.encoding:base64", ver
 android-library             = { id = "com.android.library", version.ref = "gradle-android" }
 benchmark                   = { id = "org.jetbrains.kotlinx.benchmark", version.ref = "gradle-benchmark" }
 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/blake2/README.md

@@ -0,0 +1,21 @@
+# Module blake2
+
+`Digest` implementations for BLAKE2 Hashing
+
+Implementations for:
+ - BLAKE2b
+ - BLAKE2s
+
+Implementations also available as `Mac` via [KotlinCrypto/MACs][url-macs] for keyed hashing.
+
+See [HERE][url-digest-usage] for basic usage example of `Digest`.
+
+```kotlin
+fun main() {
+    BLAKE2b(512)
+    BLAKE2s(256)
+}
+```
+
+[url-digest-usage]: https://core.kotlincrypto.org/library/digest/index.html
+[url-macs]: https://github.com/KotlinCrypto/MACs

library/blake2/src/commonMain/kotlin/org/kotlincrypto/hash/blake2/BLAKE2Digest.kt

@@ -62,8 +62,6 @@ public sealed class BLAKE2Digest: Digest {
     /**
      * Core abstraction for:
      *  - [BLAKE2s]
-     *
-     * @see [Bit64]
      * */
     public sealed class Bit32: BLAKE2Digest {
 
@@ -325,8 +323,6 @@ public sealed class BLAKE2Digest: Digest {
     /**
      * Core abstraction for:
      *  - [BLAKE2b]
-     *
-     * @see [Bit32]
      * */
     public sealed class Bit64: BLAKE2Digest {
 

library/blake2/src/commonMain/kotlin/org/kotlincrypto/hash/blake2/BLAKE2b.kt

@@ -21,6 +21,10 @@ import org.kotlincrypto.core.InternalKotlinCryptoApi
  * BLAKE2b implementation
  *
  * https://datatracker.ietf.org/doc/rfc7693/
+ *
+ * https://www.blake2.net/blake2.pdf
+ *
+ * [macs-blake2](https://github.com/KotlinCrypto/MACs/tree/master/library/blake2)
  * */
 public class BLAKE2b: BLAKE2Digest.Bit64 {
 
@@ -83,6 +87,8 @@ public class BLAKE2b: BLAKE2Digest.Bit64 {
      *  - [keyLength] is greater than 64
      *  - [salt] is non-null and not exactly 16 bytes in length
      *  - [personalization] is non-null and not exactly 16 bytes in length
+     *
+     * @suppress
      * */
     @InternalKotlinCryptoApi
     public constructor(

library/blake2/src/commonMain/kotlin/org/kotlincrypto/hash/blake2/BLAKE2s.kt

@@ -23,6 +23,10 @@ import org.kotlincrypto.core.InternalKotlinCryptoApi
  * BLAKE2s implementation
  *
  * https://datatracker.ietf.org/doc/rfc7693/
+ *
+ * https://www.blake2.net/blake2.pdf
+ *
+ * [macs-blake2](https://github.com/KotlinCrypto/MACs/tree/master/library/blake2)
  * */
 public class BLAKE2s: BLAKE2Digest.Bit32 {
 
@@ -85,6 +89,8 @@ public class BLAKE2s: BLAKE2Digest.Bit32 {
      *  - [keyLength] is greater than 32
      *  - [salt] is non-null and not exactly 8 bytes in length
      *  - [personalization] is non-null and not exactly 8 bytes in length
+     *
+     * @suppress
      * */
     @InternalKotlinCryptoApi
     public constructor(

library/md/README.md

@@ -0,0 +1,19 @@
+# Module md
+
+`Digest` implementations for MD Hashing
+
+Implementations for:
+ - MD5
+
+Implementations also available for `Hmac` via [KotlinCrypto/MACs][url-macs].
+
+See [HERE][url-digest-usage] for basic usage example of `Digest`.
+
+```kotlin
+fun main() {
+    MD5()
+}
+```
+
+[url-digest-usage]: https://core.kotlincrypto.org/library/digest/index.html
+[url-macs]: https://github.com/KotlinCrypto/MACs