1

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)
davidalayachew
  • 1,279
  • 1
  • 11
  • 22

1 Answers1

3

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.

Knight Industries
  • 1,325
  • 10
  • 20
  • 1
    Although the maintainers seem to be aware of this warning and even [included it in one of the integration tests](https://github.com/openjdk/valhalla/blob/lworld/test/langtools/jdk/javadoc/doclet/testRecordTypes/TestRecordTypes.java#L579). – Knight Industries Apr 05 '22 at 21:57
  • Thank you very much! This is a well researched answer that proves its point well. I wanted to make sure I wasn't wrong before pushing forward. I would award the bounty now, but StackOverflow is telling me I have to wait 18 hours. – davidalayachew Apr 06 '22 at 01:55
  • Thank you again! I am going to submit this as a bug to Oracle, and hope that they resolve this, much like they did the other one. – davidalayachew Apr 09 '22 at 03:48
  • Submitted a bug to Oracle, and they finally created a ticket for it, but they immediately resolved it because they did not follow the directions I asked them to, and thus, didn't get the warning that we both found. Though, in their defense, I put this under the wrong ticket subcomponent, so I understand the confusion. You can follow along here -- https://bugs.java.com/bugdatabase/view_bug.do?bug_id=JDK-8284994 – davidalayachew Apr 19 '22 at 11:19
  • 2
    The problem has been resolved, and it is coming out in Java 19! Thank you again! https://bugs.openjdk.java.net/browse/JDK-8284994 – davidalayachew May 16 '22 at 05:46