RFR: 8271090: Missing API docs in scenegraph classes

[Kevin Rushforth]

On Fri, 22 Oct 2021 11:23:07 GMT, Ajit Ghaisas <aghaisas at openjdk.org> wrote:

> This PR fixes javadoc warnings primarily in javafx.graphics module along with a remaining few in javafx.fxml, javafx.base and javafx.media modules.
> 
> Note :
> - The javadoc needs to be generated with the JDK 18 EA build.
> - There are still few remaining warnings in these modules. The root cause is different and they will be addressed under [JDK-8270996](https://bugs.openjdk.java.net/browse/JDK-8270996)

I left two comments below.

modules/javafx.graphics/src/main/java/javafx/stage/Stage.java line 1307:

> 1305:      * @return the full screen exit hint property
> 1306:      * @since JavaFX 8.0
> 1307:      */

Instead of this change, I recommend moving the docs that are currently on the getter to the private `fullScreenExitHint` field. As mentioned in the review for PR #646 the best practice is that exactly one of the private field or the property method should have docs, and that the getter and setter should have no docs (absent a compelling reason).

modules/javafx.graphics/src/main/java/javafx/stage/Window.java line 781:

> 779:      * Sets the {@code Scene} of this {@code Window}.
> 780:      * @param value the {@code Scene} to be set
> 781:      */

The javadoc tool automatically generates docs for this setter (you can see this from the generated docs without this change), including the property description, so this change will actually lose information. I'm guessing that the tool warns on this method because the setter is protected (rather than public). So we should probably file a bug against the javadoc tool. As for how to fix it, you can either suppress the warning (I'm not sure whether that's possible), or you can copy the information from the property method with a leading sentence that matches what javadoc _would_ generate.

-------------

PR: https://git.openjdk.java.net/jfx/pull/650