RFR: 8271090: Missing API docs in scenegraph classes [v3]

[Nir Lisker]

On Tue, 26 Oct 2021 09:54:43 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)
>
> Ajit Ghaisas has updated the pull request incrementally with one additional commit since the last revision:
> 
>   fix review comments

Added a few more comments, otherwise looks fine.

modules/javafx.graphics/src/main/java/javafx/stage/PopupWindow.java line 156:

> 154: 
> 155:     /**
> 156:      * Creates a {@code PopupWindow}.

The `PopupWIndow` class is abstract. Do we still keep this wording?

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

> 229: 
> 230:     /**
> 231:      * Creates a {@code Window}.

This is also a constructor for subclasses to call.

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

> 785:      * reference before the new one gains it. You may swap {@code Scene}s on
> 786:      * a {@code Window} at any time, even if it is an instance of {@code Stage}
> 787:      * and with {@link Stage#fullScreenProperty() fullScreen} set to true.

"true" should be in `{@code}`

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

> 786:      * a {@code Window} at any time, even if it is an instance of {@code Stage}
> 787:      * and with {@link Stage#fullScreenProperty() fullScreen} set to true.
> 788:      * If the width or height of this {@code Window} have never been set by the

I would start a new paragraph here since it switches from talking about a scene to talking about sizes.

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

> 788:      * If the width or height of this {@code Window} have never been set by the
> 789:      * application, setting the scene will cause this {@code Window} to take its
> 790:      * width or height from that scene.  Resizing this window by end user does

Extra space before "Resizing"

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

> 792:      *
> 793:      * An {@link IllegalStateException} is thrown if this property is set
> 794:      * on a thread other than the JavaFX Application Thread.</p>

Shouldn't this be in a `@throws`?

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

> 794:      * on a thread other than the JavaFX Application Thread.</p>
> 795:      *
> 796:      * @defaultValue null

`{@code null}`

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

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