Dokka 2.0 migration dokkaJavadoc issue

[driessamyn]

Describe the bug
I am converting my project to Dokka 2, follwoing the documentation and running into a couple of issues.

gradle dokkaJavadoc executes succssfully but does not generate anything.

Adding

tasks.register<Jar>("dokkaJavadocJar") {
    dependsOn(tasks.dokkaJavadoc)
    from(tasks.dokkaJavadoc.flatMap { it.outputDirectory })
    archiveClassifier.set("javadoc")
}

as indicated in the docs here and running gradle dokkaJavadocJar gives the following error:

* What went wrong:
Execution failed for task ':kapper:dokkaJavadocJar'.
> Cannot query the value of this provider because it has no value available.
  The value of this provider is derived from:
    - task ':kapper:dokkaJavadoc' property 'outputDirectory'

The same error is produced for the dokkaHtmlJar example.

Expected behaviour

gradle dokkaJavadoc to generate javadocs
gradle dokkaJavadocJar to complete successfully.

To Reproduce

gradle dokkaJavadoc
gradle dokkaJavadocJar

Dokka configuration

id("org.jetbrains.dokka") version "2.0.0"
id("org.jetbrains.dokka-javadoc") version "2.0.0"

...

tasks.register<Jar>("dokkaHtmlJar") {
    dependsOn(tasks.dokkaHtml)
    from(tasks.dokkaHtml.flatMap { it.outputDirectory })
    archiveClassifier.set("html-docs")
}

tasks.register<Jar>("dokkaJavadocJar") {
    dependsOn(tasks.dokkaJavadoc)
    from(tasks.dokkaJavadoc.flatMap { it.outputDirectory })
    archiveClassifier.set("javadoc")
}

Installation

• Operating system: macOS
• Build tool: Gradle 8.12
• Dokka version: 2.0.0

[driessamyn]

FYI, full gradle file and project are here: https://github.com/driessamyn/kapper/blob/fix-dokka/lib/build.gradle.kts

[driessamyn]

Any update on this or guidance on how v2 can be used?

It's a bit odd it was released as a stable version, but it's spewing warnings at me to upgrade with it doesn't seem like the V2 API (or docs) are complete?

[adam-enko]

Hi @driessamyn, thanks for reporting the issue.

I've checked the Kapper project and I reproduced error you reported.

Fix

To collect the generated docs into a JAR use different tasks:

• replace dokkaHtml with dokkaGeneratePublicationHtml
• replace dokkaJavadoc with dokkaGeneratePublicationJavadoc

// lib/build.gradle.kts

// ...

tasks.register<Jar>("dokkaHtmlJar") {
    dependsOn(tasks.dokkaHtml)
    from(tasks.dokkaGeneratePublicationHtml.flatMap { it.outputDirectory })
    archiveClassifier.set("html-docs")
}

tasks.register<Jar>("dokkaJavadocJar") {
    dependsOn(tasks.dokkaJavadoc)
    from(tasks.dokkaGeneratePublicationJavadoc.flatMap { it.outputDirectory })
    archiveClassifier.set("javadoc")
}

After this I was able to run ./gradlew dokkaJavadocJar and produce the Javadoc JAR.

Details

The tasks dokkaHtml and dokkaJavadoc are from DGPv1. Because Kapper has set the plugin mode to V2EnabledWithHelpers the DGPv1 tasks will still be present (to avoid buildscript compilation errors, which would make migration much more challenging), but are completely non-functional and will not do anything.

It's a bit odd it was released as a stable version, but it's spewing warnings at me to upgrade with it doesn't seem like the V2 API (or docs) are complete?

Please note that DGPv2 is experimental and is currently not stable.

At present there is an example demonstrating how to define the JAR tasks for Dokka HTML and Javadoc when using DPGv2 mode, but it is not yet referenced in the documentation. https://github.com/Kotlin/dokka/blob/v2.0.0/examples/gradle-v2/library-publishing-example/build.gradle.kts#L12-L22

When DGPv2 is released as stable we will update the docs to demonstrate how to produce the docs into JARs.

[driessamyn]

Thanks @adam-enko .
This as very helpful and Kapper is now using the Dokka v2 API 👍

driessamyn/kapper#63