javawarningsjavadocfalse-positive

How to JavaDoc a record without warnings from -Xdoclint?

I have been trying to familiarize myself with records, but I ran into something that really looks like a bug in Java's tool for linting JavaDoc -Xdoclint.

I tried to use this command...

 javac     -Xdoclint:all       XdoclintDoesntHandleRecordJavadocCorrectly.java

...to lint my JavaDoc for this file...

/**
 *
 * Comment.
 *
 * @param a Comment.
 * @param b Comment.
 * @param c Comment.
 *
 */
public record XdoclintDoesntHandleRecordJavadocCorrectly(
/** Comment. */
int a,
/** b Comment. */
int b,
/** @param c Comment. */
int c
) {}

...which gave me this error...

XdoclintDoesntHandleRecordJavadocCorrectly.java:14: warning: no comment
int a,
    ^
XdoclintDoesntHandleRecordJavadocCorrectly.java:16: warning: no comment
int b,
    ^
XdoclintDoesntHandleRecordJavadocCorrectly.java:18: warning: no comment
int c
    ^
3 warnings

...which makes no sense to me at all.

Is this a bug in Java's -Xdoclint tool? Normally, I wouldn't be so quick to make the claim, but this isn't the first time that -Xdoclint tool has had bugs that Java later fixed.

And finally, here is my java version.

$ java --version
java 18 2022-03-22
Java(TM) SE Runtime Environment (build 18+36-2087)
Java HotSpot(TM) 64-Bit Server VM (build 18+36-2087, mixed mode, sharing)
Solution

  • Since the Javadoc example for records in the OpenJDK repository gives the same warning, this is certainly a bug.

    edit: The Java Language Specification provides a clue:

    For each record component, a record class has a field with the same name as the record component and the same type as the declared type of the record component. This field, which is declared implicitly, is known as a component field.

    So "no comment" could well refer to this implicitly declared component field of the record class that results from the record and cannot be commented, similar to the findings from the issue you linked to.