JDK-8249634 : doclint should report implicit constructor as missing javadoc comments
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 15
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2020-07-16
  • Updated: 2021-07-29
  • Resolved: 2021-07-22
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 18
18 b08Fixed
Related Reports
Relates :  
JDK-8271159 - [REDO] JDK-8249634 doclint should report implicit constructor as missing javadoc comments
Relates :  
JDK-8071961 - Add javac lint warning when a default constructor is created
Description
If a class has an explicit constructor with no javadoc comments, then running "javadoc -Xdoclint:missing" will produce a warning regarding the missing comments. If, however, no constructor is defined in the source file, which will cause an implicit no-arg constructor to be generated, no warning is generated. Since the implicit constructor will not have any documentation (same as in the explicit case), it would be nice to produce a warning.

To reproduce this, run the attached program as follows:

javadoc -d build --source-path src -Xdoclint:missing pkg
Comments
Changeset: c1c40489 Author: Jonathan Gibbons <jjg@openjdk.org> Date: 2021-07-22 18:52:19 +0000 URL: https://git.openjdk.java.net/jdk/commit/c1c404896ca2791ad348a4cf482beb2c2ad98464
22-07-2021
Deferring to 17, to better understand/document the implications of the change.
24-12-2020
An alternative might be an option (which definitely requires a CSR) or a backdoor to allow default constructors without a warning.
24-12-2020
While the fix is relatively easy, the change in behavior causes major test breakage, because of the many small test classes we have with default constructors. Even though these are test classes, the effect is onerous enough that it might deserve a CSR, or at least a discussion, to decide if it is appropriate for 16.
24-12-2020
The fix for javac (and javadoc) may be as easy as deleting the call that suppresses the check, because when doclint sees the code, a no-args constructor has really been added to the tree, which (in other circumstances) I'd say was a mistake ;-) The (minor) challenge is just to craft a suitable new error message, since otherwise you get a "missing comment" message on the class declaration.
24-12-2020
-- deleted incorrect comment about default constructors -- Separately, we need to consider is this (just) a javadoc/doclint fix, or should we get the same warning when running doclint from javac?
23-12-2020
Fixing this in javac as well may be more tricky, since it just invokes doclint on declarations, and we've got a situation where there's a missing declaration. While there is code in javac to detect and provide default constructors, it's not done in a way that we can easily invoke doclnt, which runs in a `TaskListener` without intruding on the general flow in the compiler itself. --- "Yesterday, upon the stair, I met a man who wasn't there! He wasn't there again today, Oh how I wish he'd go away!"
23-12-2020
Relevant code is Utils.getDocCommentTree0, lines 2718-2736 (2nd half of method) We only run doclint if there is a TreePath, meaning, item in the source code. Other mandated methods are handled in first part of method, where they lookup synthetic text from the cache.
23-12-2020
Test case confirmed.
23-12-2020
There are two different policies in play, here, which may be one too many. For the implicit default constructor, the original mandated method, no comment is generated, and no warning is given if it is missing. For all more recent mandated methods (enum values(), valueOf(String, record accessors) comments are automatically generated along with the method. That being said, the status quo for the implicit default constructor has existed for long enough that we should accept it, and accept that it is different from other mandated methods. --- And, note to self: With the recent changes to detecting missing comments in javadoc, we should verify (i.e. add unit tests) that we do not get warnings on other mandated methods.
16-07-2020
We have run into this in the JDK from time to time, including in the java.compiler module (JDK-8230734).
16-07-2020