JDK-8325071 : javadoc generates incorrect missing comment warning in one case for JavaFX property
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 21,22,23
  • Priority: P4
  • Status: Closed
  • Resolution: Won't Fix
  • Submitted: 2024-01-31
  • Updated: 2024-12-05
  • Resolved: 2024-12-05
Related Reports
Relates :  
JDK-8314590 - ☂ Eliminate all javadoc warnings in JavaFX
Relates :  
JDK-8345583 - Block tag lookup triggers doclint warning for missing doc comment
Description
I haven't been able to narrow this down to a simple test program.

To reproduce this, build the JavaFX docs from the jfx22 branch of the GitHub jfx repo using JDK 21 (or later) as follows:

git clone https://github.com/openjdk/jfx.git
cd jfx
git checkout jfx22
bash gradlew javadoc

It will produce 186 warnings, 2 of which are incorrect.

jfx/modules/javafx.controls/src/main/java/javafx/scene/control/Skinnable.java:55: warning: no comment
    public void setSkin(Skin<?> value);
                ^
jfx/modules/javafx.controls/src/main/java/javafx/scene/control/Skinnable.java:57: warning: no comment
    public Skin<?> getSkin();
                   ^

There is a corresponding skinProperty() method in the same interface, and the javadoc tool correctly produces the docs for these two methods from the property.

WORKAROUND: Annotate the two methods with `@SuppressWarnings("doclint:missing")`
Comments
Closing as won't fix. Filed JDK-8345583 for the underlying issue.
05-12-2024
What happens is that the javadoc SpecTaglet class introduced in JDK-8226279 looks for `@spec` tags in all inherited doc comments. Since none of the members constituting the property contain a `@spec` tag, the search reaches the undocumented `setSkin` and `getSkin` methods which triggers the warning. This would also have happened for the `@see` tag (which uses a similar lookup mechanism) if javadoc did not generate synthetic `@see` tags for JavaFX properties. It would be nice if we could suppress warnings for "non-essential" comment lookups like this, but it's not a trivial change. Given that there exists a workaround using `@SuppressWarnings("doclint:missing")` I will close this as "won't fix" for now, but I'll file a bug for the underlying issue.
05-12-2024