From 3b3085fa5d7d6f4e1bb3bf2d2d524cc803d351c2 Mon Sep 17 00:00:00 2001 From: Ben Woodworth Date: Sun, 5 Nov 2023 00:00:28 -0400 Subject: [PATCH] Add Dokka and a KDoc publishing workflow --- .github/workflows/publish.yml | 40 +++++++++++++++++-- README.md | 2 +- build.gradle.kts | 9 +++++ src/commonMain/kotlin/ParameterDelegate.kt | 1 + src/commonMain/kotlin/Parameterize.kt | 5 +++ .../kotlin/ParameterizeConfiguration.kt | 23 +++++++++++ src/commonMain/kotlin/ParameterizeContext.kt | 1 + .../kotlin/ParameterizeFailedError.kt | 2 + src/commonMain/kotlin/ParameterizeFailure.kt | 24 +++++++++++ 9 files changed, 103 insertions(+), 4 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 252a0ed..b870327 100644 --- a/.github/workflows/publish.yml +++ b/.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 diff --git a/README.md b/README.md index 614a3f1..848f971 100644 --- a/README.md +++ b/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/) diff --git a/build.gradle.kts b/build.gradle.kts index 6113ed9..c9e221f 100644 --- a/build.gradle.kts +++ b/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().configureEach { + dokkaSourceSets.configureEach { + reportUndocumented = true + failOnWarning = true + } +} + kotlin { explicitApi() diff --git a/src/commonMain/kotlin/ParameterDelegate.kt b/src/commonMain/kotlin/ParameterDelegate.kt index 99d2220..e409deb 100644 --- a/src/commonMain/kotlin/ParameterDelegate.kt +++ b/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 diff --git a/src/commonMain/kotlin/Parameterize.kt b/src/commonMain/kotlin/Parameterize.kt index 37f8763..e3a49c3 100644 --- a/src/commonMain/kotlin/Parameterize.kt +++ b/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 parameter(arguments: Iterable): Parameter = Parameter(arguments) + /** @suppress */ public operator fun Parameter.provideDelegate(thisRef: Any?, property: KProperty<*>): ParameterDelegate = @Suppress("UNCHECKED_CAST") state.declareParameter(property as KProperty, arguments) + /** @suppress */ public operator fun ParameterDelegate.getValue(thisRef: Any?, property: KProperty<*>): T = @Suppress("UNCHECKED_CAST") state.getParameterArgument(this, property as KProperty) + /** @suppress */ @JvmInline public value class Parameter internal constructor( internal val arguments: Iterable diff --git a/src/commonMain/kotlin/ParameterizeConfiguration.kt b/src/commonMain/kotlin/ParameterizeConfiguration.kt index 0476d45..1334885 100644 --- a/src/commonMain/kotlin/ParameterizeConfiguration.kt +++ b/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 ) { + /** @see ParameterizeFailedError */ public operator fun ParameterizeFailedError.Companion.invoke(): ParameterizeFailedError = ParameterizeFailedError(recordedFailures, failureCount, iterationCount, completedEarly) } diff --git a/src/commonMain/kotlin/ParameterizeContext.kt b/src/commonMain/kotlin/ParameterizeContext.kt index c7f2193..94a70b5 100644 --- a/src/commonMain/kotlin/ParameterizeContext.kt +++ b/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 } diff --git a/src/commonMain/kotlin/ParameterizeFailedError.kt b/src/commonMain/kotlin/ParameterizeFailedError.kt index 4902f2a..1dcb1c9 100644 --- a/src/commonMain/kotlin/ParameterizeFailedError.kt +++ b/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) diff --git a/src/commonMain/kotlin/ParameterizeFailure.kt b/src/commonMain/kotlin/ParameterizeFailure.kt index cafea97..cb43f9c 100644 --- a/src/commonMain/kotlin/ParameterizeFailure.kt +++ b/src/commonMain/kotlin/ParameterizeFailure.kt @@ -2,10 +2,21 @@ 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> ) { + /** @suppress */ override fun toString(): String = "ParameterizeFailure(" + "failure=$failure" + @@ -13,10 +24,23 @@ public class ParameterizeFailure internal constructor( ")" + /** + * A [parameter] and its [argument] when the [failure] was occurred. + */ public class Argument internal constructor( + /** + * The Kotlin property for the parameter. + */ public val parameter: KProperty, + + /** + * 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" /**