Dokka 0.10 Kotlin Javadoc Workaround

Help/Discuss
1

I’m looking for the best workaround for this Dokka issue: https://github.com/Kotlin/dokka/issues/294

Dokka is kind of like Javadoc but for Kotlin. Dokka 0.10.1 doesn’t work if you compile with JDK 10 or greater. It gives an error like:

Execution failed for task ':dokka'. com/sun/tools/doclets/formats/html/HtmlDoclet

I have two possible workarounds so far. The first creates a nearly empty Javadoc.jar file (containing only a Manifest). From build.gradle.kts:

java {
    withJavadocJar()
    withSourcesJar()
}

I also tried throwing the dokka docs (still HTML docs like Javadoc but not following any other Javadoc conventions) into the javadoc.jar like this:

java {
//    withJavadocJar() // REMOVED THIS LINE
    withSourcesJar()
}

tasks {
    val dokka by getting(DokkaTask::class) {
        outputFormat = "html"
        outputDirectory = "$buildDir/dokka"
    }
}

tasks.register<Jar>("javadocJar") {
    archiveClassifier.set("javadoc")
    dependsOn("dokka")
    from("$buildDir/dokka")
}

Is one of these a better workaround? Is this the best gradle .kts way to write it?

2

Hello,

I am not sure what you are asking about:

  • A way to run Dokka while Gradle runs with Java 10+?
  • A way to replace the content of the javadoc JAR with dokka generated files?
  • Something else?

Note that if you replace withJavadocJar() with a custom task, you are also missing the whole wiring done to prepare for publication in case the maven-publish plugin is applied.

3

Thank you for your response. I believe there is currently no way to run Dokka while while Gradle runs with Java 10+. I’m asking about the best workaround.

I believe you are suggesting I still use the built-in withJavadocJar() task. To do that I’d have to rename my custom task and… declare a dependency or something? At what phase?

4

Sorry, I still am not sure about what you expect the outcome to be.

Do you want the <project>-<version>-javadoc.jar to contain the Dokka HTML files when running with Java < 10?
Or something else, including when running with Java 10+?

5

I only care about running with Java 10+ (well, 11+ now, if you want to be specific).

Before Java 10, Dokka could make HTML files that matched the output of what you’d expect from running the javadoc program against pure-Java source files. With Java 10, that feature of Dokka is broken. It only produces its own very different HTML files.

To answer part of my own question, I think it’s probably better to put some form of documentation into javadoc.jar than to upload an empty one. Maybe I could stick an index.html in Dokka’s output that just redirects to Dokka’s files which are in a subdirectory. I know how to make that HTML file, just not how to tell Gradle to stick it in there, or when to stick it in (between building the HTML files and jarring them up).

Is that a good idea? If so, what’s the best way to implement that in Gradle? I’d like something I could copy to other projects easily.