JDK-8275784 : Bogus warning generated for record with compact constructor
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 15,17,18
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2021-10-19
  • Updated: 2022-07-27
  • Resolved: 2022-06-28
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 19 JDK 20
19 b29Fixed 20Fixed
Related Reports
Relates :  
Description
A DESCRIPTION OF THE PROBLEM :
If a record has a compact constructor, a comment for the constructors describing the parameters is required even if the parameters have already been described in the record comment.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Simply "javadoc X.java"

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
No warnings
ACTUAL -
X.java:7: warning: no @param for i
    public X { }

---------- BEGIN SOURCE ----------
/**
 * Comment.
 * @param i comment
 */
public record X(int i) {
    /** Comment. */
    public X { }
}
---------- END SOURCE ----------

CUSTOMER SUBMITTED WORKAROUND :
Move the parameter description to the comment of the constructor.

FREQUENCY : always



Comments
Changeset: a814293e Author: Jonathan Gibbons <jjg@openjdk.org> Date: 2022-06-28 15:54:52 +0000 URL: https://git.openjdk.org/jdk19/commit/a814293e1fb724cb85e66501ed7a8185409642df
28-06-2022

A pull request was submitted for review. URL: https://git.openjdk.org/jdk19/pull/70 Date: 2022-06-24 20:53:30 +0000
24-06-2022

The message is coming from doclint.
24-06-2022

The notable issue here is that no parameters are given in the compact constructor.
24-06-2022

It's related to but different from JDK-8275199. Right now, the general policy for the comments on the "special" methods for a record is, "if you provide anything for a "special" method, you must provide everything."
30-11-2021

This is similar to, but different from, the issues in JDK-8275199. Currently, the policy for generating comments for the "special" members of a record is, "if you provide anything, you must provide everything". This includes `@param` and `@return` tags. javadoc does not (currently) perform more detailed analysis to determine if any parts of the comment are "missing" and could be inferred and added to the otherwise incomplete user-provided comment. You can see this by providing partial comments to any of the other "special" members, not just the compact constructor. The more interesting question may be, if one does decide to explicitly provide an implementation for anything that could be auto-generated, should you also be expected to provide a comment to go along with that implementation?
24-11-2021

The issue relates to JDK-8275199.
22-10-2021