Skip to content

Fix javadoc errors in the release javadoc build - #9282

Open
linzch3 wants to merge 1 commit into
apache:masterfrom
linzch3:javadoc-fix-errors
Open

linzch3 wants to merge 1 commit into
apache:masterfrom
linzch3:javadoc-fix-errors

Conversation

@linzch3

@linzch3 linzch3 commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Part of #7616 (STORM-3834). This first PR fixes all the javadoc errors; more will follow for the warnings.

What is the purpose of the change

Running the javadoc command from the release steps on master:

mvn javadoc:aggregate -DreportOutputDirectory=./docs/ -DdestDir=javadocs -Dnotimestamp=true -pl '!storm-shaded-deps'

finishes with BUILD SUCCESS, but javadoc reports 124 errors (the Maven output stops at the first 100) and the generated pages carry "diagnostic markers for invalid input". All of them are comment problems:

  • <p/> is not allowed in HTML5 javadoc (67 of them). I turned these into a blank line plus <p> in front of the next paragraph, the style the checkstyle JavadocParagraph rule asks for
  • bare <, > and & in text, e.g. <= 0, Map<>, the arrows in CheckPointState and SupervisorClient: escaped, or wrapped in {@code}
  • <li> without a surrounding list in BaseResourceAwareStrategy, ConstraintSolverStrategy and ServerUtils: wrapped in <ul>/<ol>
  • stray </p> after a </ul> or </pre>, a stray < in OutputCollector, <pre>< in RocksDbKey
  • @throws Exception on CaptureLoad.checkInitialization, which doesn't throw
  • the Markdown code fences in FluxShellBolt/FluxShellSpout became <pre> blocks

I also fixed the six empty <p> tag warnings while I was there. Comments only, no code changes.

The remaining ~18,400 warnings are almost all missing comments (no comment, no @param, no @return, default constructors). That needs real doc text across many modules, so I'll split it into smaller PRs by module after this one, unless you'd rather handle the warnings differently.

Happy to adjust if you'd prefer a different approach, or to split this PR by module if it's easier to review.

How was the change tested

With JDK 25 and Maven 3.9.11:

  • The release command above: 124 errors before (counted by re-running javadoc with -Xmaxerrs), 0 after. Warnings went from 18,405 to 18,395. No more "diagnostic markers" note.
  • mvn validate -Pexternals,examples -pl '!storm-shaded-deps' (checkstyle) passes.

An AI assistant helped draft this change; I reviewed it and take responsibility for it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant