CI does not run Javadoc, so doclint guards nothing

[paulhoadley]

#36 removed -Xdoclint:none from the POM, so Javadoc lint is enforced again. But #20 had unbound the javadoc plugin from package to keep builds fast, and both workflows run mvn --batch-mode --update-snapshots verify, which therefore never invokes javadoc.

The result is that doclint only runs when someone remembers to type mvn javadoc:javadoc. A Javadoc regression reaches master unnoticed, which makes #36's last step decorative.

Verified at the 0.7 release: breaking a @param deliberately fails mvn javadoc:javadoc locally, and CI stays green.

Options, roughly in order of preference:

• Add javadoc:javadoc to the workflow's Maven invocation. One line, keeps the plugin unbound for ordinary local builds, and costs a few seconds per CI run.
• Bind javadoc to verify in the POM. Catches it for everyone, but puts the cost back on every local build, which is what POM hygiene: release flag, plugin pins, metadata, unused dependency #20 removed.
• Add a separate workflow job so a Javadoc failure is distinguishable from a test failure at a glance.

Noticed while releasing 0.7, and deliberately not fixed then, to keep a CI change out of a release commit.

[paulhoadley]

Done in a456c68, taking the first option: the goal is added to the workflow, as its own step, and the plugin stays unbound from the lifecycle so local builds keep the speed #20 gave them. It runs on both JDKs, because doclint belongs to the JDK and a newer one can be stricter — JDK 25 is clean too, as the run confirms.

The step alone would have enforced nothing, though, and that is the part worth recording.

This issue says, and #36's commit message says, that deliberately breaking a @param fails mvn javadoc:javadoc. It does not. A missing @param is a doclint warning, and the goal exits zero. Measured rather than inferred: removing the @param for Tracer.trace's address and reading the exit code gives 0, with the warning printed and BUILD SUCCESS. So adding the step would have reproduced the exact problem this issue describes — a check that runs and guards nothing.

failOnWarnings is therefore set on the javadoc plugin as well. With it, the same break exits 1; without it, 0. A clean tree exits 0 with no warnings at all. All three states were checked, and the deliberate break reverted.

One cost, recorded in the POM beside the setting: detectLinks and the JDK API link are fetched over the network — the generated docs do contain live docs.oracle.com URLs — so a network failure now fails the build instead of quietly producing docs with dead links. If that ever becomes annoying, detectJavaApiLink=false makes the check hermetic at the cost of those links.

Verified in CI on the pushed commit: the Javadoc step reports success on both build (21) and build (25).