fix: stop javadoc from reporting the imported tree's missing comments - #45
Merged
Merged
Conversation
#44 removed the javadoc errors but left 12,486 warnings, all of them from doclint's `missing` group: 6,744 "no comment", 2,332 "no @return", and @param/@throws gaps throughout the imported OpenSearch tree. That is upstream's documentation coverage, not a defect introduced here, and it buries anything worth reading in the build output. Set `doclint` to `all,-missing`, so the groups that catch real breakage - syntax, HTML, accessibility and references - still fail the build, while completeness is left alone. It also pins behaviour that otherwise depends on the JDK in use. `mvn javadoc:javadoc` and `mvn -Prelease javadoc:jar` now report 0 errors and 0 warnings, and still generate all 4,902 pages.
marevol
added a commit
that referenced
this pull request
Sep 14, 2026
#45 silenced doclint's `missing` group because the imported OpenSearch tree carried 12,486 warnings. That hid the finding rather than fixing it, and left the one javadoc group that says whether an API is usable turned off for the whole repository, our own code included. The tree is documented now and the override is gone, so `doclint` runs at full strength again. Every edit was placed at the file, line and column javadoc itself reported, and the run was repeated until it reported nothing: - 6,747 doc comments written for undocumented members - 7,682 `@param`, 5,027 `@return` and 1,245 `@throws` tags - 218 main descriptions for comments that began with a tag - 212 implicit constructors declared, each with the access the compiler already gave it, because a default constructor has nowhere to carry a comment Prose comes from the declaration: `getIndices()` is "Returns the indices.", `writeTo` is "Writes this instance to the given output.", `IOException` is "if an I/O error occurs". Existing comment text is never rewritten - tags are inserted into the block in conventional order, and the only lines removed are single-line comments expanded to three, plus one `{}` split so a constructor could go in. Placement needed care in four ways that a naive pass gets wrong: a doc comment under an annotation is not a doc comment, `no main description` points inside the comment rather than at the declaration, a trailing `// note` stops a line looking finished, and enum constants each need their own anchor. `mvn javadoc:javadoc` and `mvn -Prelease javadoc:jar` report 0 errors and 0 warnings under `-Xdoclint:all`, generating the same 4,902 pages; 636 tests pass.
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
1 participant
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.
Follow-up to #44. That one cleared the javadoc errors; this clears the noise
left behind.
What was still being reported
12,486 warnings, every one of them from doclint's
missinggroup:@return@throwsforjava.io.IOException@paramgaps (request,in,<T>,name, …)All of it is the imported OpenSearch tree's own documentation coverage. Nothing
here is going to fill it in, and at that volume it hides anything that would
actually be worth reading —
[WARNING] Javadoc Warningswas the only line thebuild printed about a twelve-thousand-entry list.
Change
The groups that catch real breakage —
syntax,html,accessibility,reference— keep failing the build, so a malformed comment or a link to somethingthat was pruned is still caught the way #44's 201 broken references were. Only
completeness is switched off.
It also removes a JDK dependency:
missingis the group whose reporting variesmost between JDK versions, so pinning it makes the outcome the same wherever the
build runs.
Verification
mvn javadoc:javadocmvn -Prelease javadoc:jarChecked against a fresh clone of
mainas well, to be sure the result is not anartefact of a local working tree.