-
Bug
-
Resolution: Fixed
-
P4
-
18
-
b02
-
generic
-
generic
A DESCRIPTION OF THE PROBLEM :
When annotations on an element are placed before the Javadoc comment, the comment is not properly recognized as documenting the element.
This might be caught by `-Xdoclint:missing`, but often doclint is disabled or developers do not pay close attention to the warnings it produces.
And this potential bug pattern of placing annotations in front of the Javadoc comment is quite common.
Even the JDK source code contains occurrences of this for internal methods, e.g.:
https://github.com/openjdk/jdk/blob/d191e475168f203bb448c4977f8d6d77b8658d25/src/java.base/share/classes/java/util/regex/Pattern.java#L2127-L2131
Not sure if any of the specifications define where Javadoc comments may be placed, and whether that specification needs to be updated in case the current javadoc behavior is adjusted.
STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Run `javadoc -Xdoclint:all Test.java` with the below source code as `Test.java`
EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The class documentation should be visible in the generated output
ACTUAL -
The javadoc tool emits the following warning and the class documentation is missing:
>Test.java:5: warning: no comment
> public interface Test {}
---------- BEGIN SOURCE ----------
@Deprecated
/**
* Class doc
*/
public interface Test {}
---------- END SOURCE ----------
When annotations on an element are placed before the Javadoc comment, the comment is not properly recognized as documenting the element.
This might be caught by `-Xdoclint:missing`, but often doclint is disabled or developers do not pay close attention to the warnings it produces.
And this potential bug pattern of placing annotations in front of the Javadoc comment is quite common.
Even the JDK source code contains occurrences of this for internal methods, e.g.:
https://github.com/openjdk/jdk/blob/d191e475168f203bb448c4977f8d6d77b8658d25/src/java.base/share/classes/java/util/regex/Pattern.java#L2127-L2131
Not sure if any of the specifications define where Javadoc comments may be placed, and whether that specification needs to be updated in case the current javadoc behavior is adjusted.
STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Run `javadoc -Xdoclint:all Test.java` with the below source code as `Test.java`
EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The class documentation should be visible in the generated output
ACTUAL -
The javadoc tool emits the following warning and the class documentation is missing:
>Test.java:5: warning: no comment
> public interface Test {}
---------- BEGIN SOURCE ----------
@Deprecated
/**
* Class doc
*/
public interface Test {}
---------- END SOURCE ----------
- relates to
-
JDK-8303689 javac -Xlint could/should report on "dangling" doc comments
-
- Resolved
-