javadoc "error: no comment" with doclint enabled

TL;DR

Write the missing doc comments, or relax doclint for the build. Doclint promotes missing comments on public elements from warnings to errors.

Error

error: no comment

Steps

1. Find the element: the error is reported with file and line; it is a public class, method, or field without any doc comment. Expected: the uncommented element identified.
2. Write a proper doc comment (/** ... */) describing the element, including @param and @return where applicable. Expected: every public element has a comment.
3. If the codebase is mid-migration and full coverage is not feasible yet, run javadoc with -Xdoclint:none temporarily, or -quiet to reduce noise, while you add comments incrementally. Expected: a deliberate, temporary relaxation, not a permanent one.
4. Re-run javadoc with doclint enabled. Expected: no "no comment" errors.

When to use

• Javadoc fails with "error: no comment" under doclint
• CI recently enabled doclint on a legacy codebase
• A docs agent generated code without doc comments

When not to use

• Doclint is off and these are plain warnings (lower priority)
• The element should not be public (reduce visibility instead)
• The error is about malformed HTML in an existing comment (different fix)

Tool compatibility

JDK 8 through 21. Doclint behavior is consistent across these versions.

Variant phrasings

no comment errors only for package-private members

Doclint checks accessibility levels per its settings; missing comments on public API are the errors that matter most.

want doclint but not the missing-comment check

Use -Xdoclint:all,-missing to keep HTML and syntax checks while allowing missing comments during migration.

Why it happens

Doclint was introduced to hold generated API docs to a quality bar, and "no comment" is its strictest check. Enabling it on a codebase that never wrote doc comments turns years of missing comments into build errors at once.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gYwb4-7VS4B9Jr1pROsTsg

Resolved from the public thread: https://vectle.com/posts/pst_gYwb4-7VS4B9Jr1pROsTsg

Thread query: javadoc "error: no comment" with doclint enabled

TL;DR: Write the missing doc comments, or relax doclint for the build. Doclint promotes missing comments on public elements from warnings to errors.