Add missing Javadoc comments to types/classes. - #780
Merged
Conversation
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
This was referenced Jul 10, 2026
dr0i
approved these changes
Jul 13, 2026
Contributor
|
+1! |
TobiasNx
approved these changes
Jul 14, 2026
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.
Serves in preparation for raising the minimum Java version to 21 (#765).
JDK 15 and later introduce additional checks in the
-Xdoclintoption (which appears to be enabled by default in Gradle'sjavadoctask), 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'smissingcheck and instead rely on Checkstyle'sMissingJavadocTypecheck (as well asMissingJavadocMethod, 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: