I believe these javadoc docs (around generating a ...

# dokka

[David Herman]

I believe these javadoc docs (around generating a javadoc jar for multiplatform projects) need to be updated for Dokka 2.0.0? https://kotlinlang.org/docs/dokka-gradle.html#build-javadoc-jar

[David Herman]

(tasks.dokkaHtml and tasks.dokkaJavadoc are stuff we should migrate away from, correct?)

[David Herman]

So I got something working, and yes, the docs are out of date (and frustratingly vague, if I'm honest).

I'm writing my own internal plugin that sets up publishing logic, so this code exists in a Gradle plugin, not inside a build script.

What I have is essentially two parts (three if you include build script dependencies, although I appreciate most people won't need to do that in their own build scripts):

// Part 0
dependencies {
   implementation("org.jetbrains.dokka:org.jetbrains.dokka.gradle.plugin:2.0.0")
}

// Part 1
private const val DOKKA_HTML_JAR_TASK_NAME = "dokkaHtmlJar"

@Suppress("UNCHECKED_CAST")
val TaskContainer.dokkaHtmlJar: Provider<Jar>
    get() = named(DOKKA_HTML_JAR_TASK_NAME) as Provider<Jar>

class ExamplePlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.pluginManager.apply {
            apply("org.jetbrains.dokka")
        }

        @Suppress("UNCHECKED_CAST")
        val dokkaHtmlTask = project.tasks.named("dokkaGeneratePublicationHtml") as Provider<DokkaGenerateTask>
        project.tasks.register<Jar>(DOKKA_HTML_JAR_TASK_NAME) {
           dependsOn(dokkaHtmlTask)
           from(dokkaHtmlTask.flatMap { it.outputDirectory })
           archiveClassifier.set("javadoc")
        }

        // Workaround for <https://youtrack.jetbrains.com/issue/KT-61858>
        tasks.withType<AbstractPublishToMaven>().configureEach {
            val signingTasks = tasks.withType<Sign>()
            mustRunAfter(signingTasks)
        }
        ...
    }
}

// Part 2
publications.withType<MavenPublication>().configureEach {
    artifact(project.tasks.dokkaHtmlJar)
}

The relevant parts are that 1) the task name has changed (it is now dokkaGeneratePublicationHtml) and 2) you should reference that task inside the maven publication. You should also 3) make it so all publishing tasks run after all signing tasks, or else Gradle complains about implicit ordering.

I hope someone will update the docs. Thanks!

[Adam Semenenko]

Hi, thanks for the feedback. Dokka Gradle Plugin v2 mode is still experimental, and so the other docs are still focused on how to use DGPv1. The docs will be updated when DGPv2 is made the default mode later this year.

[Adam Semenenko]

Your code looks good, and similar to the example project for DGPv2 that demonstrates how to create a Javadoc JAR https://github.com/Kotlin/dokka/blob/fc574c855fb75a4fe30185aa9f12b74295b095d4/examples/gradle-v2/library-publishing-example/build.gradle.kts#L12-L16

[Adam Semenenko]

I have a suggestion: you could avoid the cast and @Suppress("UNCHECKED_CAST") by replacing

named(DOKKA_HTML_JAR_TASK_NAME)

with

tasks.named(DOKKA_HTML_JAR_TASK_NAME, Jar::class.java)

Gradle will do the same casting underneath, so it works the same, but I think it's neater to hide the suppressions and casting. One small difference is that named() returns a TaskProvider instead of a Provider, which is better because Gradle will be able to automatically determine the task dependencies, so manually defining the task dependency with dependsOn(dokkaHtmlTask) isn't necessary.

[CLOVIS]

tasks.named(DOKKA_HTML_JAR_TASK_NAME, Jar::class.java)

Gradle should automatically generate that accessor as tasks.dokkaHtmlJar , no?

[Adam Semenenko]

yes, if you're writing a pre-compiled script plugin, but I assumed OP is not

[David Herman]

I'm in buildSrc so yeah I think I have to generate the accessor manually? But thanks, I agree about removing the unchecked cast.

[Adam Semenenko]

it depends - if you're working in a pre-compiled script plugin (a file like my-foo-convention.gradle.kts) then the accessors should be generated automatically so you shouldn't need them, but if you're in a 'binary plugin' (a .kt file with a class like class MyFooConvention : Plugin <Project> then you won't have the generated accessors)

[David Herman]

Right, the latter