RFR: 8271090: Missing API docs in scenegraph classes

[Nir Lisker]

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)

modules/javafx.graphics/src/main/java/javafx/scene/Camera.java line 164:

> 162:     /**
> 163:      * Creates a {@code Camera}.
> 164:      */

Sine the constructor is a `protected` for an `abstract` class, it doesn't create a `Camera` in the normal sense of constructors. I would write something like "Shared constructor for subclasses of `Camera`".

modules/javafx.graphics/src/main/java/javafx/scene/paint/Material.java line 81:

> 79:     /**
> 80:      * Creates a {@code Material}.
> 81:      */

Same comment as in `Camera`.

modules/javafx.graphics/src/main/java/javafx/scene/shape/Box.java line 91:

> 89:      * Default size of the {@code Box}.
> 90:      */
> 91:     public static final double DEFAULT_SIZE = 2;

This field was exposed by mistake probably. The other shapes don't expose theirs. I recommend to deprecate for removal.

modules/javafx.graphics/src/main/java/javafx/scene/shape/Shape3D.java line 102:

> 100:     /**
> 101:      * Creates a {@code Shape3D}.
> 102:      */

Same comment as in `Camera`,

modules/javafx.media/src/main/java/javafx/scene/media/Track.java line 85:

> 83:     /**
> 84:      * Gets the <code>Map</code> containing all known metadata for this <code>Track</code>.
> 85:      * @return the <code>Map</code> containing all known metadata for this <code>Track</code>

We tend to use `{@code }` over `<code> </code>`, but I don't think it matter.

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

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