Is it possible to merge Javadocs of dependency projects that aren't subprojects?

[TomerAberbach]

Question
For example, I have the following sibling projects :

openai-java/
openai-java-client-okhttp/
openai-java-core/

Where openai-java depends on openai-java-client-okhttp and openai-java-core. I would like openai-java's Javadoc to include the Javadocs of openai-java-client-okhttp and openai-java-core.

I was looking at the Gradle Dokka documentation and it seems like it's only possible to use the dokkaJavadocCollector to merge together Javadocs of subprojects, but not arbitrary project dependencies.

Is what I want possible somehow?

Installation

• Operating system: macOS
• Build tool: Gradle v8.7
• Dokka version: 2.0.0

[whyoleg]

Hey!
First of all, I'm curious why do you need to use javadoc format instead of HTML? In that case you could also use default HTML multimodule documentation setup.

it seems like it's only possible to use the dokkaJavadocCollector to merge together Javadocs of subprojects, but not arbitrary project dependencies.

Yes, overall aggregation inside Dokka is possible only over sources, so of subprojects and dependencies are used for resolution and external links.
Additionally, with new Dokka Gradle Plugin we removed support for collector tasks as those were not properly designed and not so frequently used.
There is no direct replacement, but it's possible to register a custom source set and setup classpath and sources (from all of your three modules) so that the output will be single javadoc for those three modules.
The only known users of this such low-level APIs is Gradle DSL setup - you can take there code as an inspiration.

[TomerAberbach]

Hey! First of all, I'm curious why do you need to use javadoc format instead of HTML? In that case you could also use default HTML multimodule documentation setup.

The libraries I'm writing are written in Kotlin, but geared towards Java developers, who are used to javadocs. So ideally I could provide javadocs and keep the fact that the library is in Kotlin an implementation detail.

it seems like it's only possible to use the dokkaJavadocCollector to merge together Javadocs of subprojects, but not arbitrary project dependencies.

Yes, overall aggregation inside Dokka is possible only over sources, so of subprojects and dependencies are used for resolution and external links. Additionally, with new Dokka Gradle Plugin we removed support for collector tasks as those were not properly designed and not so frequently used. There is no direct replacement, but it's possible to register a custom source set and setup classpath and sources (from all of your three modules) so that the output will be single javadoc for those three modules. The only known users of this such low-level APIs is Gradle DSL setup - you can take there code as an inspiration.

This is mildly hacky, but I came up with the following code for the subproject:

// Redefine `dokkaJavadoc` to:
// - Depend on the root project's task for merging the docs of all the projects
// - Forward that task's output to this task's output
tasks.named("dokkaJavadoc").configure {
    actions.clear()

    val dokkaJavadocCollector = rootProject.tasks["dokkaJavadocCollector"]
    dependsOn(dokkaJavadocCollector)

    val outputDirectory = project.layout.buildDirectory.dir("dokka/javadoc")
    doLast {
        copy {
            from(dokkaJavadocCollector.outputs.files)
            into(outputDirectory)
            duplicatesStrategy = DuplicatesStrategy.INCLUDE
        }
    }

    outputs.dir(outputDirectory)
}

That way the dokkaJavadocJar task I generate for that subproject contains the javadocs of the whole project.

---

By the way, I noticed that when using Dokka Gradle plugin v1 you get deprecation warnings and are told to migrate to v2, but then the v2 pages says:

The Dokka Gradle plugin v2 is an Experimental feature. It may be changed at any time. We appreciate your feedback on GitHub.

Which then makes me nervous about migrating to v2. I'm wondering if v2 is actually is unstable as this text makes it seem?