JDK-8242607 : -Xdoclint doesn't report missing/unexpected comments
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 11,14
  • Priority: P3
  • Status: Closed
  • Resolution: Fixed
  • Submitted: 2020-04-11
  • Updated: 2024-10-23
  • Resolved: 2020-12-15
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 15 JDK 16
15Fixed 16 b01Fixed
Related Reports
Relates :  
Description
ADDITIONAL SYSTEM INFORMATION :
openjdk full version "14+36-1461"

A DESCRIPTION OF THE PROBLEM :
The behavior of Xdoclint's "missing" group doesn't work as expected for javadoc (note that it does for javac)

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
* create 2 directories, 1 named "docs", 1 named "foo"
* in "foo", create a file Doc.java as provided below
* open a terminal in "docs" and run the following 2 commands:
** javadoc -private -Xdoclint:all ../foo/Doc.java
** javac -Xdoclint:all ../foo/Doc.java

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Both commands give equivalent results and report 3 warnings, namely:
..\foo\Doc.java:4: warning: documentation comment not expected here
package foo;
^
..\foo\Doc.java:6: warning: no comment
public class Doc {
       ^
..\foo\Doc.java:8: warning: no comment
    public void bar() {
                ^
3 warnings
ACTUAL -
The javadoc command doesn't report any warnings, whereas the javac command reports the expected result.

---------- BEGIN SOURCE ----------
/**
 * Something unexpected.
 */
package foo;

public class Doc {

    public void bar() {

    }

}

---------- END SOURCE ----------

CUSTOMER SUBMITTED WORKAROUND :
Use javac instead of javadoc


Comments
Verification from the submitter: Thanks for reaching out to me. In summary: it’s fixed. Now javadoc reports the warnings about missing comments as well, so that’s indeed fixed. There’s still a difference between javac and javadoc, in that javadoc doesn’t give the warning about “documentation comment not expected here”. However, as I understand it, Jonathan addressed this difference in one of the comments: “That is less serious and is not addressed here. […] If we really want full fidelity between javac and javadoc for doclint messages, we might want to consider removing the check from javac.” I agree it’s acceptable for there to be minor differences between the 2, so I don’t think this is worth pursuing any further.
15-01-2021

Requested the submitter verify the fix with latest version of JDK 16.
13-01-2021

This was fixed back in June, but no automatically closed. commit 07e6b75ff57ce746b4fdb06e06abbd3d298cd8fa Author: Jonathan Gibbons <jjg@openjdk.org> Date: Tue Jun 9 20:05:04 2020 -0700 8242607: -Xdoclint doesn't report missing/unexpected comments Reviewed-by: ksrini
15-12-2020

It would seem the fix went to 15 under JDK-8247288, so this should not be "In progress" anymore?
14-09-2020

The reported differences are twofold, which are very different in nature. 1. javadoc does not report missing comments when it is specifically asked to check the presence with doclint. This is serious and needs to be addressed. 2. javac and javadoc have different ways to determine which places should be checked for comments. Arguably, javadoc is more "precise", because it knows which comments it needs to use -- and which it does not. "javac" has a different algorithm, meaning that it might check some places where comments are not required and will be ignored. That is less serious and is not addressed here. There are actually lots of places where a comment could be put and where it will be ignored, but in general, it is not worth checking all these places. If we really want full fidelity between javac and javadoc for doclint messages, we might want to consider removing the check from javac.
08-06-2020

The previous comment addresses 2 of the 3 warnings (the warnings about missing comments) The comment about doc comment not expected here on the package declaration is a different issue. (But still a valid issue.)
03-06-2020

The problem is in javadoc Utils.java about lines 2703-2721: the comment is not "scanned" if it is null ("missing"). if (!dcTreeCache.containsKey(element)) { if (docCommentTree != null && path != null) { if (!configuration.isAllowScriptInComments()) { try { javaScriptScanner.scan(docCommentTree, path, p -> { throw new JavaScriptScanner.Fault(); }); } catch (JavaScriptScanner.Fault jsf) { String text = resources.getText("doclet.JavaScript_in_comment"); throw new UncheckedDocletException(new SimpleDocletException(text, jsf)); } } configuration.workArounds.runDocLint(path); } dcTreeCache.put(element, duo); }
03-06-2020

Update: The same (or equivalent) options are being passed from both java and javadoc.
03-06-2020

Confirmed; very strange. doclint is certainly active, because a bad comment is detected.
03-06-2020

The observation on Windows 10: JDK 14: Fail JDK 11: Fail ILW=MML=P4
23-04-2020