skip to content

When you call `withJavadocJar()`, what does the resulting jar contain and which task does it depend on?

level: middleimportance: should knowfreq 40%

answer

  1. packages javadoc task output dir
  2. classifier javadoc
  3. implicit dependsOn javadoc
  4. doclint failure propagates
  5. Kotlin -> Dokka instead

basics

~10 s

It packages the output of the built-in javadoc task (generated HTML docs) into a jar with classifier javadoc. The javadocJar task depends on javadoc, so running it triggers doc generation first.

solid answer

~40 s

`withJavadocJar()` registers a `Jar` task named `javadocJar` with archive classifier `javadoc`. Its `from(...)` is wired to the destination directory of the standard `javadoc` task (which the `java` plugin already provides for the `main` source set). Gradle infers the task dependency, so building `javadocJar` first runs `javadoc` to generate the HTML, then zips that directory. The jar is attached to the `java` component as a documentation variant (`DocsType=javadoc`). Note it bundles whatever `javadoc` produces — if your doc comments are sparse the jar is sparse; if `javadoc` fails (e.g. strict doclint), the jar task fails too. For Kotlin you'd typically point a javadoc-style jar at Dokka output instead.

code

kotlin · 6 lines
kotlin
java { withJavadocJar() }

// relax strict doclint so the javadoc task (and thus javadocJar) doesn't fail
tasks.withType<Javadoc> {
    (options as StandardJavadocDocletOptions).addStringOption("Xdoclint:none", "-quiet")
}

go deeper

for a junior

Know it bundles generated javadoc HTML with classifier javadoc.

for a middle

Explain the implicit dependency on the javadoc task and that failures there break the jar/publish.

for a senior

Discuss doclint behavior, options tuning, and the Kotlin/Dokka substitution while keeping the variant concept.

for a principal

Standardize doc-jar policy (doclint strictness, Dokka) across modules via a convention plugin.

## What `withJavadocJar()` packages The `java` plugin already registers a `javadoc` task (type `Javadoc`) for the `main` source set. It runs the JDK `javadoc` tool and writes HTML into `build/docs/javadoc`. `withJavadocJar()` registers a `Jar` task, `javadocJar`, whose content is the **output directory of that `javadoc` task**: ```kotlin // conceptually what withJavadocJar() wires up val javadocJar by tasks.registering(Jar::class) { archiveClassifier.set("javadoc") from(tasks.named("javadoc")) } ``` Because `from(tasks.named("javadoc"))` references the task's output, Gradle records an implicit **task dependency**: `javadocJar` depends on `javadoc`. So invoking `javadocJar` (or publishing) generates the docs first. ## Consequences - **Empty or partial docs**: the jar only contains what `javadoc` emits. No source comments → mostly auto-generated signature pages. - **Doclint failures**: modern JDKs run doclint and can fail the `javadoc` task on malformed comments; that failure propagates to `javadocJar` and to publishing. You may relax it via the `javadoc` task's `options`. - **Kotlin**: the JDK `javadoc` tool doesn't understand Kotlin. Projects use Dokka and wire a `javadoc`-classified jar from Dokka's output, but the *attachment-as-variant* concept from `withJavadocJar()` is the same idea. ## Variant attachment Like sources, the javadoc jar becomes a secondary variant on the `java` component with `Category=documentation`, `DocsType=javadoc`, so `from(components["java"])` publishes it with proper module metadata.

  • What happens if the `javadoc` task fails during a publish?
    `javadocJar` depends on `javadoc`, so the failure propagates and the publish fails. Common cause is doclint rejecting malformed comments; relax via the javadoc task `options`.
  • Why doesn't `withJavadocJar()` work well for a pure-Kotlin module?
    The JDK `javadoc` tool can't process Kotlin sources, so the docs are empty/incorrect. Kotlin projects generate a javadoc-classified jar from Dokka output instead.

saying these in an interview costs you the question

  • Saying the javadoc jar contains source files — it contains generated HTML docs, not sources.
  • Assuming it always succeeds — strict doclint can fail the underlying `javadoc` task.

context

resolving links…