JDK-8249633 : doclint reports missing javadoc for JavaFX property methods that have a property description
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 15
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2020-07-16
  • Updated: 2024-12-20
  • Resolved: 2021-01-06
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 16 JDK 17
16 b32Fixed 17Fixed
Description
For JavaFX properties -- which are defined as attributes that have a xxxxProperty method that returns a subclass of javafx.beans.Observable, a getXxxx method, and an optional setXxxx method -- the description on the property itself is copied to the three public methods by the standard doclet.

When running javadoc with `-Xdoclint:missing" the methods without a javadoc comment body are flagged as missing a comment even when the property itseld does have a comment that will be copied.

This produces a few thousand warnings when build the JavaFX docs with JDK 15.

To reproduce it, either clone the jfx repo and run "gradle javadoc" or else download the JavaFX 15 SDK and run the attached test program as follows:

javadoc -d build --source-path src \
        --module-path /SOMEWHERE/javafx-sdk-15/lib \
        --add-modules javafx.base \
        -Xdoclint:all \
        pkg
Comments
Changeset: 4f914e21 Author: Jonathan Gibbons <jjg@openjdk.org> Date: 2021-01-06 19:26:17 +0000 URL: https://git.openjdk.java.net/jdk16/commit/4f914e21
06-01-2021
The root cause looks very similar to the root cause for JDK-8251200, which is about false positive messages for serialization classes, and for which a fix is already up for review (indirectly meaning, it somewhat blocks this one.) The common cause in both cases is that checking for the presence of block tags unnecessarily triggers the "missing comment" when there is no comment (and so no block tags). In this case, the code is checking if the methods in question have either `@hidden` or `@treatAsPrivate`, and so the probable fix is to include a check whether there is a comment that might contain the tags. There's one additional check to include, when it actually tries to access the doc comment, if any.
24-12-2020
Thanks for the simple example. I would not have guessed that the property method picks up its comment from the private field. This will only be fixable for javadoc -Xdoclint, not javac -Xdoclint, because of the way that properties are handled in javadoc, and the way that the descriptions are synthesized.
24-12-2020
The JavaFX SDK can be downloaded from here: https://gluonhq.com/products/javafx/ Scroll down and find the Early-Access Builds and download the JavaFX 15 SDK for your platform.
16-07-2020