diff options
| author | Leitwolf | 2026-11-15 21:07:52 +0300 |
|---|---|---|
| committer | GitHub | 2026-11-15 21:07:52 +0300 |
| commit | d719e92f9651568a1d756f06811ce53ec5febee7 (patch) | |
| tree | 9190a9a980afa2ee8ade1bbe2bd5063d500f683e | |
| parent | 584c52693097e039291321f787079145d76a3cdd (diff) | |
| parent | 8e3629745e8a57cb5290d2951a93cdfcd500f8a9 (diff) | |
| download | tazel-d719e92f9651568a1d756f06811ce53ec5febee7.tar.gz | |
Merge pull request #12 from Progmasoft/ci/dokka
Build the Dokka reference in CI
12 files changed, 103 insertions, 2 deletions
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c50a990..89bc3ee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -47,3 +47,19 @@ jobs: - name: Run the installed Tazel shell: bash run: build/install/tazel/bin/tazel version + + # The reference of the API and the Gradle plugin, and the CLI module on its own; every + # Dokka warning fails it. + - name: Dokka + if: matrix.os == 'ubuntu-26.04' + shell: bash + run: ./gradlew dokkaGenerate :dokkaGenerateModuleHtml --no-daemon + + - name: Keep the reference + if: matrix.os == 'ubuntu-26.04' + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: tazel-dokka + path: build/dokka/html/ + if-no-files-found: error + retention-days: 7 diff --git a/api/build.gradle.kts b/api/build.gradle.kts index 779c1ed..97e07e1 100644 --- a/api/build.gradle.kts +++ b/api/build.gradle.kts @@ -12,6 +12,16 @@ plugins { kotlin("jvm") `java-library` `maven-publish` + id("org.jetbrains.dokka") +} + +// The API reference. Every warning fails it, an undocumented public declaration included. +dokka { + dokkaPublications.html { failOnWarning = true } + dokkaSourceSets.configureEach { + reportUndocumented = true + jdkVersion = 25 + } } group = "com.progmasoft.tazel" diff --git a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/BuildStep.kt b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/BuildStep.kt index 0cfd280..6a7b264 100644 --- a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/BuildStep.kt +++ b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/BuildStep.kt @@ -9,11 +9,13 @@ import java.nio.file.Path /** Work a plugin adds to the build of a project; see [ExtensionScope.buildStep]. */ fun interface BuildStep { + /** Does the work of the step; [context] reaches the project, the host and the output. */ fun run(context: BuildContext) } /** What a [BuildStep] runs with. */ interface BuildContext { + /** The absolute root directory of the project. */ val projectRoot: Path /** The project the step builds. */ @@ -22,7 +24,10 @@ interface BuildContext { /** The absolute directory the build mode of the project writes artifacts to. */ val outputDirectory: Path + /** The build mode of the build: debug or release. */ val buildMode: BuildMode + + /** The machine Tazel runs on. */ val host: Host /** @@ -37,6 +42,7 @@ interface BuildContext { message: String, ) + /** Prints [message] as a warning; the build goes on. */ fun warn(message: String) /** @@ -69,7 +75,9 @@ interface BuildContext { /** The exit code of a program [BuildContext.capture] ran, and what it printed. */ data class CapturedRun( + /** The exit code of the program. */ val exitCode: Int, + /** What the program printed, its output and its errors in the order written. */ val output: String, ) diff --git a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/Host.kt b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/Host.kt index 9779ed6..986c0e2 100644 --- a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/Host.kt +++ b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/Host.kt @@ -5,6 +5,7 @@ package com.progmasoft.api.tazel.dsl.plugin +/** The operating system of a [Host]. */ enum class OperatingSystem { LINUX, MACOS, @@ -15,6 +16,7 @@ enum class OperatingSystem { UNKNOWN, } +/** The processor architecture of a [Host]. */ enum class Architecture { X86_64, AARCH64, @@ -25,7 +27,9 @@ enum class Architecture { /** The machine Tazel runs on. */ data class Host( + /** The operating system. */ val os: OperatingSystem, + /** The processor architecture. */ val architecture: Architecture, ) { /** The extension the host gives an executable file: `.exe` on Windows, none elsewhere. */ diff --git a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/PluginExtensions.kt b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/PluginExtensions.kt index 931aa66..5cc8936 100644 --- a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/PluginExtensions.kt +++ b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/PluginExtensions.kt @@ -36,7 +36,10 @@ object PluginExtensions { /** What the block of an extension can add to its project. */ interface ExtensionScope { + /** The absolute root directory of the project. */ val projectRoot: Path + + /** The machine Tazel runs on. */ val host: Host /** @@ -52,5 +55,8 @@ interface ExtensionScope { /** Provided by Tazel, which [PluginExtensions] finds as a service. Plugins do not implement it. */ interface ExtensionHost { + /** + * The scope of [extension] in the project whose file is running; see [PluginExtensions.require]. + */ fun require(extension: String): ExtensionScope } diff --git a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/ProjectPlugin.kt b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/ProjectPlugin.kt index 9e479d9..01cf567 100644 --- a/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/ProjectPlugin.kt +++ b/api/sources/main/kotlin/com/progmasoft/api/tazel/dsl/plugin/ProjectPlugin.kt @@ -25,11 +25,13 @@ const val PROJECT_PLUGIN_API_VERSION = 1 * JAR are checked before it is activated; its code is not sandboxed. */ fun interface ProjectPlugin { + /** Activates the plugin for one project, before its project files run. */ fun apply(context: ProjectPluginContext) } /** What a plugin can do while it is activated for one project. */ interface ProjectPluginContext { + /** The absolute root directory of the project. */ val projectRoot: Path /** The machine Tazel runs on. */ @@ -53,8 +55,13 @@ interface ProjectPluginContext { /** The project as a plugin sees it once its project file has run. */ interface ProjectSummary { + /** The name the project file gives the project, or `null`. */ val name: String? + + /** The version the project file gives the project, or `null`. */ val version: String? + + /** The build mode of the build. */ val buildMode: BuildMode /** The directory the build mode writes artifacts to, relative to the project root. */ diff --git a/build.gradle.kts b/build.gradle.kts index 069d56d..85fa035 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -9,6 +9,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget plugins { kotlin("jvm") version "2.4.0" id("com.diffplug.spotless") version "8.9.0" + id("org.jetbrains.dokka") version "2.3.0" application jacoco } @@ -26,6 +27,20 @@ dependencies { implementation("org.jetbrains.kotlin:kotlin-scripting-jvm:2.4.0") implementation("org.jetbrains.kotlin:kotlin-scripting-jvm-host:2.4.0") testImplementation(kotlin("test")) + // One reference for Tazel, its plugin API and its Gradle plugin. + dokka(project(":tazel-api")) + dokka(project(":tazel-gradle-plugin")) +} + +// The reference of Tazel with its API and Gradle plugin. Every warning fails it; the modules of +// the API and the Gradle plugin also fail on an undocumented public declaration, the CLI not yet. +dokka { + moduleName = "Tazel" + dokkaPublications.html { failOnWarning = true } + dokkaSourceSets.configureEach { + reportUndocumented = false + jdkVersion = 25 + } } kotlin { diff --git a/gradle-plugin/build.gradle.kts b/gradle-plugin/build.gradle.kts index 9de8c5b..48c1aba 100644 --- a/gradle-plugin/build.gradle.kts +++ b/gradle-plugin/build.gradle.kts @@ -13,6 +13,16 @@ plugins { kotlin("jvm") `java-gradle-plugin` id("com.gradle.plugin-publish") version "2.0.0" + id("org.jetbrains.dokka") +} + +// The API reference. Every warning fails it, an undocumented public declaration included. +dokka { + dokkaPublications.html { failOnWarning = true } + dokkaSourceSets.configureEach { + reportUndocumented = true + jdkVersion = 25 + } } group = "com.progmasoft.tazel" diff --git a/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginDescriptorTask.kt b/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginDescriptorTask.kt index da24708..b1c4305 100644 --- a/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginDescriptorTask.kt +++ b/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginDescriptorTask.kt @@ -26,31 +26,44 @@ import org.gradle.api.tasks.TaskAction @CacheableTask abstract class TazelPluginDescriptorTask : DefaultTask() { // A required field is optional to Gradle, so the task reports it as a tazelPlugin setting. + /** [TazelPluginExtension.group]; required. */ @get:Input @get:Optional abstract val pluginGroup: Property<String> + /** [TazelPluginExtension.name]; required. */ @get:Input @get:Optional abstract val pluginName: Property<String> + /** [TazelPluginExtension.version]; required. */ @get:Input @get:Optional abstract val pluginVersion: Property<String> + /** [TazelPluginExtension.pluginClass]; required. */ @get:Input @get:Optional abstract val pluginClass: Property<String> + /** [TazelPluginExtension.imports]. */ @get:Input abstract val imports: ListProperty<String> // `description` is a property of every task already. + /** [TazelPluginExtension.description]. */ @get:Input @get:Optional abstract val description_: Property<String> + /** [TazelPluginExtension.authors]. */ @get:Input abstract val authors: ListProperty<String> + /** [TazelPluginExtension.license]. */ @get:Input @get:Optional abstract val license: Property<String> + /** [TazelPluginExtension.homepage]. */ @get:Input @get:Optional abstract val homepage: Property<String> + /** [TazelPluginExtension.repository]. */ @get:Input @get:Optional abstract val repository: Property<String> + /** The version of the plugin API the plugin is built for. */ @get:Input abstract val apiVersion: Property<Int> + /** The directory the task writes `META-INF/` into, added to the resources of the JAR. */ @get:OutputDirectory abstract val outputDirectory: DirectoryProperty + /** Checks the settings and writes the descriptor and the service entry. */ @TaskAction fun write() { val group = required(pluginGroup, "group") diff --git a/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginPlugin.kt b/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginPlugin.kt index 274bf8d..93bf6bf 100644 --- a/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginPlugin.kt +++ b/gradle-plugin/sources/main/kotlin/com/progmasoft/tazel/gradle/TazelPluginPlugin.kt @@ -23,6 +23,7 @@ import org.gradle.api.provider.Property * `tazelApi()` takes the API of that version. */ class TazelPluginPlugin : Plugin<Project> { + /** Adds the repository, `tazelApi()`, `tazelPlugin { }` and the descriptor task to [project]. */ override fun apply(project: Project) { project.pluginManager.apply("java-library") project.repositories.maven { repository -> @@ -57,8 +58,12 @@ class TazelPluginPlugin : Plugin<Project> { } } + /** The repository, group, API version and version this Gradle plugin uses. */ companion object { + /** The Maven repository of the Tazel API. */ const val REPOSITORY = "https://maven.progmasoft.com/tazel" + + /** The group of the Tazel API, the only group taken from [REPOSITORY]. */ const val GROUP = "com.progmasoft.tazel" /** The plugin API of the Tazel this Gradle plugin belongs to. */ @@ -100,13 +105,19 @@ abstract class TazelPluginExtension { /** Packages or classes the project file imports by default, such as `com.example.cmake.*`. */ abstract val imports: ListProperty<String> + /** One sentence about the plugin, shown on Tazel Portal. */ abstract val description: Property<String> + + /** The authors of the plugin, such as `Ada Lovelace <[email protected]>`. */ abstract val authors: ListProperty<String> /** An SPDX license expression, such as `MIT`. */ abstract val license: Property<String> + /** The web page of the plugin. */ abstract val homepage: Property<String> + + /** The source repository of the plugin. */ abstract val repository: Property<String> } @@ -115,6 +126,7 @@ abstract class TazelPluginExtension { * its tests use. It is not bundled; Tazel provides it at run time. */ abstract class TazelApiDependency @Inject constructor(private val project: Project) { + /** Adds the API to `compileOnly` and `testImplementation`. */ operator fun invoke() { val coordinate = "${TazelPluginPlugin.GROUP}:tazel-api:${TazelPluginPlugin.VERSION}" project.dependencies.add("compileOnly", coordinate) diff --git a/sources/main/kotlin/com/progmasoft/tazel/driver/CcToolchain.kt b/sources/main/kotlin/com/progmasoft/tazel/driver/CcToolchain.kt index 5b20912..e1f148e 100644 --- a/sources/main/kotlin/com/progmasoft/tazel/driver/CcToolchain.kt +++ b/sources/main/kotlin/com/progmasoft/tazel/driver/CcToolchain.kt @@ -109,7 +109,7 @@ fun zigTriple(triple: TargetTriple): String { private val VENDORS = setOf("unknown", "pc", "apple", "w64", "none", "suse", "redhat") -/** The file names a triple gives the outputs of a target named [name]. */ +/** The file names a triple gives the outputs of a target, from the name of the target. */ object OutputNames { fun executable(name: String, os: Os) = if (os == Os.WINDOWS) "$name.exe" else name diff --git a/sources/main/kotlin/com/progmasoft/tazel/driver/SourceTools.kt b/sources/main/kotlin/com/progmasoft/tazel/driver/SourceTools.kt index 81724cc..1a1ce3d 100644 --- a/sources/main/kotlin/com/progmasoft/tazel/driver/SourceTools.kt +++ b/sources/main/kotlin/com/progmasoft/tazel/driver/SourceTools.kt @@ -197,7 +197,7 @@ private fun json(text: String): String { } /** - * Runs clang-tidy on translation units, with the compilation database in [database], [jobs] at a + * Runs clang-tidy on translation units, with the compilation database [lint] is given, [jobs] at a * time. */ class Linter( |