Enable strict Javadoc doclint (all,-missing) and fix all doclint issues#197
Merged
vharseko merged 1 commit intoJul 16, 2026
Merged
Conversation
Make the Javadoc build fail on any doclint error or warning across all
modules, and clean up every existing issue so it stays green from
JDK 17 through JDK 26.
pom.xml:
- add an inherited `doclint` property (all,-missing) and reference it
from maven-javadoc-plugin via ${doclint} (was doclint=none)
- bump maven-javadoc-plugin to 3.12.0 and enable failOnWarnings
- put j2objc-annotations on the Javadoc classpath so Guava's
@ReflectionSupport(Level.FULL) resolves instead of warning
Fix 218 doclint issues in 92 files across 26 modules: block @inheritdoc
on overrides, self-closing <p/>, broken {@link}/@see references,
<tt>/<blockquote>/<pre> HTML, bad HTML entities, and stale
@throws/@param/@return tags. Javadoc comments only; no code changes.
Verified: full-reactor `mvn javadoc:jar` builds clean with zero warnings
on both JDK 17 and JDK 26.
vharseko
added
documentation
maximthomas
approved these changes
Jul 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Make the Javadoc build strict (
failOnWarnings=true) and fix every existing doclint error/warning so it stays green across the CI JDK matrix (17–26).pom.xmldoclintproperty (all,-missing) and reference it frommaven-javadoc-pluginvia${doclint}(wasdoclint=none).maven-javadoc-plugin3.11.2 → 3.12.0 and enable<failOnWarnings>true</failOnWarnings>.j2objc-annotations:3.0.0to the Javadoc classpath via<additionalDependencies>so Guava's@ReflectionSupport(Level.FULL)resolves instead of emitting a warning that would tripfailOnWarnings.There were no per-module doclint overrides to drop — only the root pom carried it.
Doclint fixes
218 issues in 92 files across 26 modules — Javadoc comments/headers only, no code changes:
@inheritDocon overrides → redundant comment removed<p/>/</p/>, empty<p>,<tt>→<code>,<blockquote>/<pre>nesting,<caption>for tables, bad&{entities{@link}/{@Link}/@see, nested{@link}@throws/@param/@return(not thrown / wrong name / on void), duplicate@returnVerification
Full-reactor
mvn javadoc:jarbuilds clean with 0 doclint warnings and produces all 40 module javadoc jars on both JDK 17 and JDK 26. No Java module is skipped; only pom/JS aggregator modules without Java sources are inherently skipped by the plugin.