docs: document the forked tree instead of switching the check off - #47
Merged
Merged
Conversation
#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
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.
#45 turned doclint's
missinggroup off because the imported OpenSearch treecarried 12,486 warnings. That was a workaround: it hid the finding instead of
fixing it, and it switched off the one javadoc group that says whether an API is
usable — for the whole repository,
org.codelibs.fesen.clientincluded.The tree is documented now, and
<doclint>all,-missing</doclint>is gone.What was missing
@param@return@throwsTwo passes were needed: a member with no comment at all is reported only as "no
comment", and its missing tags surface once it has one. The loop ran until javadoc
reported nothing.
How it was written
Every edit was placed at the file, line and column javadoc itself reported, so
existing comment text is never rewritten — tags are inserted into the block in
conventional order (
@param,@return,@throws, then whatever the block alreadyhad, including
@opensearch.internal).Prose is derived from the declaration, in the house style the client packages
already use:
writeTois "Writes this instance to the given output.",IOExceptionis "if anI/O error occurs",
StreamInputconstructors are "Creates a new X by reading itfrom the given input.", a
ParseFieldconstant is "The NAME constant."The 212 constructors
A default constructor has no source to attach a comment to, so nothing in a
comment can satisfy doclint. Each is now declared explicitly with the access the
compiler already gave it — the same access as its class, which is what an
implicit constructor has. Semantically a no-op; 205
public, 5protected, 2package-private.
Placement, four ways it goes wrong
These each broke a run before being handled:
annotation as the start of the declaration, so a
/** */after@Deprecatedisan ordinary comment and the member stays undocumented. Comments go above the
topmost annotation.
no main descriptionpoints inside the comment, not at the declaration —the opposite of every other finding. Anchoring on the reported line inserted a
nested
/**into an existing block.// notestops a line looking finished, soint x; // pkg-privateread as a continuation and the next member's comment landed on it. Stripping it
has to respect string literals and their escapes.
,, so they all collapsed onto the first constant.Verification
mvn javadoc:javadoc-Xdoclint:allmvn -Prelease javadoc:jarmvn testThe diff is comments, blank lines and the 212 constructors. The only source lines
removed are single-line comments expanded to three, and one
{}split open so aconstructor could go inside it.