Skip to content

Add missing Javadoc comments to types/classes. - #780

Merged
blackwinter merged 1 commit into
masterfrom
765-addMissingJavadocType
Jul 14, 2026
Merged

Add missing Javadoc comments to types/classes.#780
blackwinter merged 1 commit into
masterfrom
765-addMissingJavadocType

Conversation

@blackwinter

Copy link
Copy Markdown
Member

Serves in preparation for raising the minimum Java version to 21 (#765).

JDK 15 and later introduce additional checks in the -Xdoclint option (which appears to be enabled by default in Gradle's javadoc task), requiring Javadoc for public and protected (and even some private!?) types and members. In order to avoid this hassle (for the time being), we disable DocLint's missing check and instead rely on Checkstyle's MissingJavadocType check (as well as MissingJavadocMethod, introduced in #396). This only applies to public scope, though.

An alternative approach would be to individually suppress the warnings right where they're originating from. This would still be quite a pain, but it would make it explicit where documentation is missing (according to DocLint).

The documentation added here is intentionally curt. If you feel strongly about expanding some of it, please add concrete suggestions. Otherwise, we can deal with it later (maybe even transfer the Fix command documentation from the README to the individual classes and generate the Markdown from those).

Future steps:

  • "warning: no main description" (JDK-8272374: doclint should report missing "body" comments)
  • "warning: use of default constructor, which does not provide a comment" (JDK-8249634: doclint should report implicit constructor as missing javadoc comments)
  • More Javadoc checks

Providing Java 21 forward compatibility (#765; see below).

JDK 15 and later introduce additional checks in the `-Xdoclint` option (which appears to be enabled by default in Gradle's `javadoc` task), requiring Javadoc for public and protected (and even some private!?) types and members. In order to avoid this hassle (for the time being), we disable DocLint's `missing` check and instead rely on Checkstyle's `MissingJavadocType` check (as well as `MissingJavadocMethod`, introduced in #396). This only applies to _public_ scope, though.

- "Missing a Javadoc comment. [MissingJavadocType]"
- "warning: empty <p> tag"

--------

* JDK 21:

525 warning: no comment
  1 warning: empty <p> tag
 26 warning: no main description
 13 warning: use of default constructor, which does not provide a comment
@dr0i dr0i removed their assignment Jul 13, 2026
@TobiasNx

Copy link
Copy Markdown
Contributor

+1!

@blackwinter
blackwinter merged commit 682da89 into master Jul 14, 2026
2 checks passed
@github-project-automation github-project-automation Bot moved this from Review to Done in Metafacture Jul 14, 2026
@blackwinter
blackwinter deleted the 765-addMissingJavadocType branch July 14, 2026 11:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants