Add Dokka and a KDoc publishing workflow

.github/workflows/publish.yml

@@ -3,7 +3,7 @@ name: Publish
 on:
   push:
     tags: [ 'v*' ]
-    branches: [ 'main' ]
+    branches: [ 'main', 'publishing' ]
 
 env:
   OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
@@ -13,12 +13,12 @@ env:
   SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}
 
 jobs:
-  publish:
+  publish-maven:
     strategy:
       matrix:
         runner: [ ubuntu-latest, macos-latest, windows-latest ]
 
-    name: 'Publish: ${{ matrix.runner }}'
+    name: 'Publish to Maven: ${{ matrix.runner }}'
     runs-on: ${{ matrix.runner }}
     steps:
       - uses: actions/checkout@v3
@@ -31,3 +31,37 @@ jobs:
 
       - name: Publish to Maven
         run: ./gradlew ciPublish
+
+  publish-kdoc:
+    name: 'Publish KDoc'
+    needs: publish-maven
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up JDK
+        uses: actions/setup-java@v3
+        with:
+          java-version: '17'
+          distribution: 'adopt'
+
+      - name: Build KDoc
+        run: ./gradlew dokkaHtml
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: './build/dokka/html'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -2,7 +2,7 @@
 
 [![Maven Central](https://img.shields.io/maven-central/v/com.benwoodworth.parameterize/parameterize)](https://search.maven.org/search?q=g:com.benwoodworth.parameterize)
 [![Sonatype Nexus (Snapshots)](https://img.shields.io/nexus/s/com.benwoodworth.parameterize/parameterize?server=https%3A%2F%2Fs01.oss.sonatype.org)](https://s01.oss.sonatype.org/content/repositories/snapshots/com/benwoodworth/parameterize/)
-[![KDoc](https://img.shields.io/badge/api-KDoc-blue)](https://benwoodworth.github.io/parameterize)
+[![KDoc](https://img.shields.io/badge/api-KDoc-blue)](https://benwoodworth.github.io/Parameterize/parameterize/com.benwoodworth.parameterize/parameterize.html)
 [![Kotlin](https://img.shields.io/badge/kotlin-1.9.20-blue.svg?logo=kotlin)](http://kotlinlang.org)
 [![Slack channel](https://img.shields.io/badge/chat-slack-blue.svg?logo=slack)](https://kotlinlang.slack.com/messages/parameterize/)
 

build.gradle.kts

@@ -1,8 +1,10 @@
 import org.gradle.kotlin.dsl.support.uppercaseFirstChar
+import org.jetbrains.dokka.gradle.DokkaTask
 import org.jetbrains.kotlin.gradle.plugin.KotlinTargetWithTests
 
 plugins {
     kotlin("multiplatform") version "1.9.20"
+    id("org.jetbrains.dokka") version "1.9.10"
     id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.13.2"
     id("parameterize.library-conventions")
 }
@@ -11,6 +13,13 @@ repositories {
     mavenCentral()
 }
 
+tasks.withType<DokkaTask>().configureEach {
+    dokkaSourceSets.configureEach {
+        reportUndocumented = true
+        failOnWarning = true
+    }
+}
+
 kotlin {
     explicitApi()
 

src/commonMain/kotlin/ParameterDelegate.kt

@@ -32,6 +32,7 @@ import kotlin.reflect.KProperty
  *   through the current iterator.
  */
 
+/** @suppress */
 public class ParameterDelegate<@Suppress("unused") out T> internal constructor() {
     /*
      * The internal state does not use the generic type, so T is purely for

src/commonMain/kotlin/Parameterize.kt

@@ -128,9 +128,11 @@ internal data object ParameterizeContinue : Throwable()
 
 internal class ParameterizeException(override val message: String) : Exception(message)
 
+/** @see parameterize */
 public class ParameterizeScope internal constructor(
     private val state: ParameterizeState,
 ) {
+    /** @suppress */
     override fun toString(): String =
         state.getFailureArguments().joinToString(
             prefix = "ParameterizeScope(",
@@ -161,15 +163,18 @@ public class ParameterizeScope internal constructor(
     public fun <T> parameter(arguments: Iterable<T>): Parameter<T> =
         Parameter(arguments)
 
+    /** @suppress */
     public operator fun <T> Parameter<T>.provideDelegate(thisRef: Any?, property: KProperty<*>): ParameterDelegate<T> =
         @Suppress("UNCHECKED_CAST")
         state.declareParameter(property as KProperty<T>, arguments)
 
+    /** @suppress */
     public operator fun <T> ParameterDelegate<T>.getValue(thisRef: Any?, property: KProperty<*>): T =
         @Suppress("UNCHECKED_CAST")
         state.getParameterArgument(this, property as KProperty<T>)
 
 
+    /** @suppress */
     @JvmInline
     public value class Parameter<out T> internal constructor(
         internal val arguments: Iterable<T>

src/commonMain/kotlin/ParameterizeConfiguration.kt

@@ -1,11 +1,21 @@
 package com.benwoodworth.parameterize
 
+import com.benwoodworth.parameterize.ParameterizeConfiguration.Builder
 import kotlin.native.concurrent.ThreadLocal
 
+/**
+ * Reusable [parameterize] configuration options.
+ *
+ * Can be used with [ParameterizeContext] to provide defaults for all [parameterize] calls in scope.
+ */
 public class ParameterizeConfiguration private constructor(
+    /** @see Builder.onFailure */
     public val onFailure: OnFailureScope.(failure: Throwable) -> Unit,
+
+    /** @see Builder.onComplete */
     public val onComplete: OnCompleteScope.() -> Unit,
 ) {
+    /** @suppress */
     @ThreadLocal
     public companion object {
         internal val default: ParameterizeConfiguration = Builder(null).build()
@@ -17,11 +27,13 @@ public class ParameterizeConfiguration private constructor(
             Builder(from).apply(builderAction).build()
     }
 
+    /** @suppress */
     override fun toString(): String =
         "ParameterizeConfiguration(" +
             "onFailure=$onFailure, " +
             "onComplete=$onComplete)"
 
+    /** @see ParameterizeConfiguration */
     public class Builder internal constructor(from: ParameterizeConfiguration?) {
         /**
          * Invoked after each failing iteration to configure how a failure should be handled.
@@ -66,6 +78,7 @@ public class ParameterizeConfiguration private constructor(
         )
     }
 
+    /** @see Builder.onFailure */
     public class OnFailureScope internal constructor(
         private val state: ParameterizeState,
 
@@ -102,8 +115,16 @@ public class ParameterizeConfiguration private constructor(
         public var recordFailure: Boolean = false
     }
 
+    /** @see Builder.onComplete */
     public class OnCompleteScope internal constructor(
+        /**
+         * The total number of iterations completed.
+         */
         public val iterationCount: Long,
+
+        /**
+         * The number of failing iterations.
+         */
         public val failureCount: Long,
 
         /**
@@ -115,8 +136,10 @@ public class ParameterizeConfiguration private constructor(
          */
         public val completedEarly: Boolean,
 
+        /** @see OnFailureScope.recordFailure */
         public val recordedFailures: List<ParameterizeFailure>
     ) {
+        /** @see ParameterizeFailedError */
         public operator fun ParameterizeFailedError.Companion.invoke(): ParameterizeFailedError =
             ParameterizeFailedError(recordedFailures, failureCount, iterationCount, completedEarly)
     }

src/commonMain/kotlin/ParameterizeContext.kt

@@ -52,6 +52,7 @@ package com.benwoodworth.parameterize
  * implement it in the way that was described here.
  */
 public interface ParameterizeContext {
+    /** @see ParameterizeConfiguration */
     public val parameterizeConfiguration: ParameterizeConfiguration
 }
 

src/commonMain/kotlin/ParameterizeFailedError.kt

@@ -20,6 +20,7 @@ public class ParameterizeFailedError internal constructor(
     internal val completedEarly: Boolean
 ) : AssertionError() {
     // TODO: Use context receiver instead of companion + pseudo constructor
+    /** @suppress */
     public companion object;
 
     init {
@@ -32,6 +33,7 @@ public class ParameterizeFailedError internal constructor(
         }
     }
 
+    /** @suppress */
     override val message: String = buildString {
         append("Failed ")
         append(failureCount)

src/commonMain/kotlin/ParameterizeFailure.kt

@@ -2,21 +2,45 @@ package com.benwoodworth.parameterize
 
 import kotlin.reflect.KProperty
 
+/**
+ * A [failure] thrown from a [parameterize] iteration, and the [arguments] that caused it.
+ */
 public class ParameterizeFailure internal constructor(
+    /**
+     * The failure thrown in a [parameterize] iteration.
+     */
     public val failure: Throwable,
+
+    /**
+     * The parameter arguments when the [failure] occurred.
+     */
     public val arguments: List<Argument<*>>
 ) {
+    /** @suppress */
     override fun toString(): String =
         "ParameterizeFailure(" +
                 "failure=$failure" +
                 ", arguments=$arguments" +
                 ")"
 
 
+    /**
+     * A [parameter] and its [argument] when the [failure] was occurred.
+     */
     public class Argument<out T> internal constructor(
+        /**
+         * The Kotlin property for the parameter.
+         */
         public val parameter: KProperty<T>,
+
+        /**
+         * The [parameter]'s argument when the [failure] was occurred.
+         */
         public val argument: T
     ) {
+        /**
+         * Returns `"parameter = argument"`, with the [parameter] name and [argument] value.
+         */
         override fun toString(): String = "${parameter.name} = $argument"
 
         /**