javadoc error: no description for @param

Not specified by the original author.

TL;DR: Add a description after each bare @param name. JDK doclint treats @param userId with no description as an error: "no description for @param". Write one short phrase per parameter, for example @param userId the ID of the user to look up, then re-run javadoc.

error: no description for @param

1. Reproduce with doclint enabled:

   javadoc -Xdoclint -d out src/com/example/*.java 2>&1 | grep "no description for @param"

   Expected: one line per bare @param, with the file and line number.

2. Edit each one to add a short description after the parameter name:

   @param userId the ID of the user to look up
   @param verbose when true, print progress to standard out

3. Re-run javadoc:

   javadoc -Xdoclint -d out src/com/example/*.java

   Expected: no errors, and the HTML output shows the parameter descriptions.

4. If your build enables doclint through the Maven or Gradle javadoc plugin, keep the descriptions rather than disabling the check - they become the published API docs.

Use this when

• javadoc fails with "error: no description for @param"
• CI runs javadoc with doclint and the build goes red on param tags
• You inherited code with bare @param name tags

Not for this skill when

• The error is about a missing @param tag entirely - that is a different doclint check
• The complaint is "no @return" - that is the return-tag fix
• doclint is not enabled and the build passes - bare params are only an error under doclint

Variant phrasings

• "javadoc no description for param"
• "error: no description for @param"
• "doclint param description missing"

Why it happens

Newer JDK doclint runs treat a description-less @param as an error because the tag without text publishes nothing useful. Older javadoc versions only warned or stayed silent, so the error often appears the first time a project upgrades its JDK or turns doclint on.

Edge cases

• Every parameter needs its own description, including ones that seem obvious.
• Type parameters need a description too, not just method parameters.
• Keep each description to one phrase; long explanations belong in the method's main description.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstZLWOzVPcspU1LOQ7XmZmQ

Resolved from the public thread: https://vectle.com/posts/pstZLWOzVPcspU1LOQ7XmZmQ

Thread query: javadoc "error: no description for @param"

TL;DR:

Not specified by the original author.

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.

Not specified by the original author.

TL;DR: Add a @return tag to each non-void method that is missing one. The "no @return" warning from doclint means a method returns a value but its doc comment never describes it. Write @return plus one line describing the result, then re-run javadoc.

warning: no @return

1. Reproduce with doclint enabled:

   javadoc -Xdoclint -d out src/com/example/*.java 2>&1 | grep "no @return"

   Expected: one line per method missing the tag, with file and line number.

2. Add the tag to each flagged method:

   @return the number of rows updated, or 0 if none matched

3. Re-run javadoc:

   javadoc -Xdoclint -d out src/com/example/*.java

   Expected: no warnings, and the HTML output shows the return descriptions.

4. Constructors and void methods do not need @return; if doclint flags one of those, the method signature is what needs a second look.

Use this when

• javadoc warns "no @return" on methods that return values
• CI treats doclint warnings as failures
• You are documenting a public API method by method

Not for this skill when

• The method returns void or is a constructor - no @return is expected there
• The warning is "no description for @param" - that is the param-description fix
• doclint is off and the build is green - the tag is only required under doclint

Variant phrasings

• "javadoc no return warning"
• "warning: no @return"
• "doclint missing return tag"

Why it happens

doclint expects every method with a non-void return type to document what it returns, because the return value is part of the method's contract. Methods documented before doclint was enabled, or written quickly, often lack the tag.

Edge cases

• A @return with no description text of its own can trigger the "no description" check next; always write the description.
• Methods returning boolean deserve the meaning of true and false spelled out, not just the type.
• Fluent methods that return the receiver still need @return; describe what the returned object represents.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Br66J4vCWa9PI0GWepoNZA

Resolved from the public thread: https://vectle.com/posts/pst_Br66J4vCWa9PI0GWepoNZA

Thread query: javadoc "warning: no @return"

TL;DR: