This is a follow-on to JDK-8249633. We noticed this recently when we switched to using JDK 16 as the boot JDK for building JavaFX 17.

Running doclint  on the JavaFX API classes reports missing javadoc comments for JavaFX properties where the docs are on the property method instead of the (private) property object.

If the docs are either on the private xxxxx property object or on the xxxxxProperty() method, the correct javadocs will be generated. For example:

case 1: docs on the property object (this is the more common case)

    /**
     * The foo property.
     */
    private DoubleProperty foo;

    public final DoubleProperty fooProperty();

    public final double getFoo();

    public final void setFoo(double foo);


case 2: docs on the property method

    private DoubleProperty bar;

    /**
     * The bar property.
     * @return the property object
     */
    public final DoubleProperty barProperty();

    public final double getBar();

    public final void setBar(double bar);


Both cases will generate the correct docs, but in the latter case, an incorrect "missing comments" warning is generated.

I can create a test case, or you can reproduce this by cloning https://github.com/openjdk/jfx.git and building the docs as follows:

$ bash gradlew --info javadoc

If I increase the max warnings we get a total of 528 warnings. Some of the warnings are very likely valid, but most of the ones I spot checked are because of this bug.