Skip to content

docs: document the forked tree instead of switching the check off - #47

Merged
marevol merged 1 commit into
mainfrom
fix/javadoc-document-fork
Sep 14, 2026
Merged

marevol merged 1 commit into
mainfrom
fix/javadoc-document-fork

Conversation

@marevol

@marevol marevol commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

#45 turned doclint's missing group off because the imported OpenSearch tree
carried 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.client included.

The tree is documented now, and <doclint>all,-missing</doclint> is gone.

What was missing

count finding
6,744 no comment
2,652 no @param
2,332 no @return
326 no @throws
216 no main description
212 use of default constructor, which does not provide a comment

Two 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 already
had, including @opensearch.internal).

Prose is derived from the declaration, in the house style the client packages
already use:

/**
 * Returns the indices.
 *
 * @return the indices
 */
public Map<String, ClusterIndexHealth> getIndices() {

writeTo is "Writes this instance to the given output.", IOException is "if an
I/O error occurs", StreamInput constructors are "Creates a new X by reading it
from the given input.", a ParseField constant 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, 5 protected, 2
package-private.

Placement, four ways it goes wrong

These each broke a run before being handled:

  • A doc comment under an annotation is not a doc comment. javac treats the
    annotation as the start of the declaration, so a /** */ after @Deprecated is
    an ordinary comment and the member stays undocumented. Comments go above the
    topmost annotation.
  • no main description points 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.
  • A trailing // note stops a line looking finished, so int x; // pkg-private
    read as a continuation and the next member's comment landed on it. Stripping it
    has to respect string literals and their escapes.
  • Enum constants end in ,, so they all collapsed onto the first constant.

Verification

mvn javadoc:javadoc BUILD SUCCESS — 0 errors, 0 warnings under -Xdoclint:all
mvn -Prelease javadoc:jar BUILD SUCCESS — 0 errors, 0 warnings
mvn test 636 tests, 0 failures — OpenSearch 3/2/1 and Elasticsearch 8/7 containers included
generated pages 4,902 — unchanged

The 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 a
constructor could go inside it.

#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.
@marevol marevol self-assigned this Sep 14, 2026
@marevol
marevol merged commit d09b075 into main Sep 14, 2026
1 check passed
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