8271090: Missing API docs in scenegraph classes

Reviewed-by: kcr, nlisker

modules/javafx.base/src/main/java/javafx/util/converter/FormatStringConverter.java

@@ -43,6 +43,10 @@ public class FormatStringConverter<T> extends StringConverter<T> {
 
     // ------------------------------------------------------------ Constructors
 
+    /**
+     * Creates a {@code FormatStringConverter} for the given {@code Format} instance.
+     * @param format the {@code Format} instance
+     */
     public FormatStringConverter(@NamedArg("format") Format format) {
         this.format = format;
     }

modules/javafx.fxml/src/main/java/javafx/fxml/LoadException.java

@@ -34,18 +34,34 @@
 public class LoadException extends IOException {
     private static final long serialVersionUID = 0;
 
+    /**
+     * Creates a default {@code LoadException}.
+     */
     public LoadException() {
         super();
     }
 
+    /**
+     * Creates a {@code LoadException} with the given message.
+     * @param message the message
+     */
     public LoadException(String message) {
         super(message);
     }
 
+    /**
+     * Creates a {@code LoadException} with the given {@code Throwable} cause.
+     * @param cause the {@code Throwable} cause
+     */
     public LoadException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * Creates a {@code LoadException} with the given message and {@code Throwable} cause.
+     * @param message the message
+     * @param cause the {@code Throwable} cause
+     */
     public LoadException(String message, Throwable cause) {
         super(message, cause);
     }

modules/javafx.graphics/src/main/java/javafx/print/PageLayout.java

@@ -120,6 +120,10 @@ public final class PageLayout {
         this.bMargin = bottomMargin;
     }
 
+    /**
+     * Gets the {@code PageOrientation}.
+     * @return the {@code PageOrientation}
+     */
     public PageOrientation getPageOrientation() {
         return orient;
     }

modules/javafx.graphics/src/main/java/javafx/scene/AccessibleAttribute.java

@@ -793,6 +793,10 @@ public enum AccessibleAttribute {
         this.returnClass = returnClass;
     }
 
+    /**
+     * Gets the type of {@code AccessibleAttribute}.
+     * @return the type of {@code AccessibleAttribute}
+     */
     public Class<?> getReturnType() {
         return returnClass;
     }

modules/javafx.graphics/src/main/java/javafx/scene/Camera.java

@@ -159,6 +159,9 @@ public Point3D pickProjectPlane(Camera camera, double x, double y) {
         CameraHelper.initHelper(this);
     }
 
+    /**
+     * Constructor for subclasses to call.
+     */
     protected Camera() {
         InvalidationListener dirtyTransformListener = observable
                 -> NodeHelper.markDirty(this, DirtyBits.NODE_CAMERA_TRANSFORM);

modules/javafx.graphics/src/main/java/javafx/scene/Node.java

@@ -9148,8 +9148,9 @@ public StyleableProperty<Boolean> getStyleableProperty(Node node) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/Scene.java

@@ -1662,7 +1662,8 @@ protected void onChanged(Change<String> c) {
     private ObjectProperty<String> userAgentStylesheet = null;
 
     /**
-     * @return the userAgentStylesheet property.
+     * Gets the userAgentStylesheet property.
+     * @return the userAgentStylesheet property
      * @see #getUserAgentStylesheet()
      * @see #setUserAgentStylesheet(String)
      * @since  JavaFX 8u20

modules/javafx.graphics/src/main/java/javafx/scene/SubScene.java

@@ -646,7 +646,8 @@ void processCSS() {
 
     private ObjectProperty<String> userAgentStylesheet = null;
     /**
-     * @return the userAgentStylesheet property.
+     * Gets the userAgentStylesheet property.
+     * @return the userAgentStylesheet property
      * @see #getUserAgentStylesheet()
      * @see #setUserAgentStylesheet(String)
      * @since  JavaFX 8u20

modules/javafx.graphics/src/main/java/javafx/scene/image/ImageView.java

@@ -836,8 +836,9 @@ public StyleableProperty<String> getStyleableProperty(ImageView n) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/layout/Background.java

@@ -118,8 +118,9 @@ public final class Background {
                             BACKGROUND_SIZE));
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {
         return STYLEABLES;

modules/javafx.graphics/src/main/java/javafx/scene/layout/Border.java

@@ -147,8 +147,9 @@ public final class Border {
                             BORDER_IMAGE_INSETS));
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {
         return STYLEABLES;

modules/javafx.graphics/src/main/java/javafx/scene/layout/FlowPane.java

@@ -939,8 +939,9 @@ public StyleableProperty<Number> getStyleableProperty(FlowPane node) {
 
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/layout/GridPane.java

@@ -2483,8 +2483,9 @@ public StyleableProperty<Number> getStyleableProperty(GridPane node) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/layout/HBox.java

@@ -733,8 +733,9 @@ public StyleableProperty<Number> getStyleableProperty(HBox node) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/layout/Region.java

@@ -3677,8 +3677,9 @@ public StyleableProperty<Insets> getStyleableProperty(Region node) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/layout/StackPane.java

@@ -386,8 +386,9 @@ public StyleableProperty<Pos> getStyleableProperty(StackPane node) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/layout/TilePane.java

@@ -1180,8 +1180,9 @@ public StyleableProperty<Number> getStyleableProperty(TilePane node) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/layout/VBox.java

@@ -653,8 +653,9 @@ public StyleableProperty<Number> getStyleableProperty(VBox node) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/paint/Material.java

@@ -76,6 +76,9 @@ PhongMaterial maybe the first and only material in FX8 (see 3D conceptual implem
      No plan to support Multi-texture
      */
 
+    /**
+     * Constructor for subclasses to call.
+     */
     protected Material() {
         if (!Platform.isSupported(ConditionalFeature.SCENE3D)) {
             String logname = Material.class.getName();

modules/javafx.graphics/src/main/java/javafx/scene/shape/Rectangle.java

@@ -467,8 +467,9 @@ public StyleableProperty<Number> getStyleableProperty(Rectangle node) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/shape/Shape.java

@@ -893,8 +893,9 @@ public StyleableProperty<Number> getStyleableProperty(Shape node) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/shape/Shape3D.java

@@ -97,6 +97,9 @@ public boolean doComputeContains(Node node, double localX, double localY) {
 
     private static final PhongMaterial DEFAULT_MATERIAL = new PhongMaterial();
 
+    /**
+     * Constructor for subclasses to call.
+     */
     protected Shape3D() {
         if (!Platform.isSupported(ConditionalFeature.SCENE3D)) {
             String logname = Shape3D.class.getName();

modules/javafx.graphics/src/main/java/javafx/scene/text/Text.java

@@ -1481,8 +1481,9 @@ public StyleableProperty<Number> getStyleableProperty(Text node) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      * @since JavaFX 8.0
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {

modules/javafx.graphics/src/main/java/javafx/scene/text/TextFlow.java

@@ -599,8 +599,9 @@ public StyleableProperty<Number> getStyleableProperty(TextFlow node) {
     }
 
     /**
-     * @return The CssMetaData associated with this class, which may include the
-     * CssMetaData of its superclasses.
+     * Gets the {@code CssMetaData} associated with this class, which may include the
+     * {@code CssMetaData} of its superclasses.
+     * @return the {@code CssMetaData}
      */
     public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {
         return StyleableProperties.STYLEABLES;

modules/javafx.graphics/src/main/java/javafx/stage/PopupWindow.java

@@ -152,6 +152,9 @@ public void invalidated(final Observable observable) {
     private WeakChangeListener<Boolean> weakOwnerNodeListener = new WeakChangeListener(changeListener);
     private TreeShowingExpression treeShowingExpression;
 
+    /**
+     * Constructor for subclasses to call.
+     */
     public PopupWindow() {
         final Pane popupRoot = new Pane();
         popupRoot.setBackground(Background.EMPTY);

modules/javafx.graphics/src/main/java/javafx/stage/Stage.java

@@ -1273,9 +1273,6 @@ public final ObjectProperty<KeyCombination> fullScreenExitKeyProperty() {
         return fullScreenExitCombination;
     }
 
-    private final ObjectProperty<String> fullScreenExitHint =
-            new SimpleObjectProperty<String>(this, "fullScreenExitHint", null);
-
     /**
      * Specifies the text to show when a user enters full screen mode, usually
      * used to indicate the way a user should go about exiting out of full
@@ -1289,9 +1286,11 @@ public final ObjectProperty<KeyCombination> fullScreenExitKeyProperty() {
      * value of this property will be ignored, in which case the
      * default message will be displayed.
      * </p>
-     * @param value the string to be displayed.
      * @since JavaFX 8.0
      */
+    private final ObjectProperty<String> fullScreenExitHint =
+            new SimpleObjectProperty<String>(this, "fullScreenExitHint", null);
+
     public final void setFullScreenExitHint(String value) {
         fullScreenExitHint.set(value);
     }

modules/javafx.graphics/src/main/java/javafx/stage/Window.java

@@ -227,6 +227,9 @@ public static ObservableList<Window> getWindows() {
     @SuppressWarnings("removal")
     final AccessControlContext acc = AccessController.getContext();
 
+    /**
+     * Constructor for subclasses to call.
+     */
     protected Window() {
         // necessary for WindowCloseRequestHandler
         initializeInternalEventDispatcher();
@@ -759,18 +762,43 @@ public Object getUserData() {
      * a different {@code Window} will cause the old {@code Window} to lose the
      * reference before the new one gains it. You may swap {@code Scene}s on
      * a {@code Window} at any time, even if it is an instance of {@code Stage}
-     * and with {@link Stage#fullScreenProperty() fullScreen} set to true.
-     * If the width or height of this {@code Window} have never been set by the
+     * and with {@link Stage#fullScreenProperty() fullScreen} set to {@code true}.
+     * <p>If the width or height of this {@code Window} have never been set by the
      * application, setting the scene will cause this {@code Window} to take its
-     * width or height from that scene.  Resizing this window by end user does
-     * not count as setting the width or height by the application.
+     * width or height from that scene. Resizing this {@code Window} by end user does
+     * not count as setting the width or height by the application.</p>
      *
-     * An {@link IllegalStateException} is thrown if this property is set
-     * on a thread other than the JavaFX Application Thread.
+     * <p>An {@link IllegalStateException} is thrown if this property is set
+     * on a thread other than the JavaFX Application Thread.</p>
      *
-     * @defaultValue null
+     * @defaultValue {@code null}
      */
     private SceneModel scene = new SceneModel();
+
+    /**
+     * Sets the value of the {@code scene} property.
+     *
+     * <p>The {@code Scene} to be rendered on this {@code Window}. There can only
+     * be one {@code Scene} on the {@code Window} at a time, and a {@code Scene}
+     * can only be on one {@code Window} at a time. Setting a {@code Scene} on
+     * a different {@code Window} will cause the old {@code Window} to lose the
+     * reference before the new one gains it. You may swap {@code Scene}s on
+     * a {@code Window} at any time, even if it is an instance of {@code Stage}
+     * and with {@link Stage#fullScreenProperty() fullScreen} set to {@code true}.</p>
+     * <p>If the width or height of this {@code Window} have never been set by the
+     * application, setting the scene will cause this {@code Window} to take its
+     * width or height from that scene. Resizing this {@code Window} by end user does
+     * not count as setting the width or height by the application.</p>
+     *
+     * @throws IllegalStateException if this property is set on a thread other than
+     * the JavaFX Application Thread.
+     *
+     * @defaultValue {@code null}
+     *
+     * @param value the value for the {@code scene} property
+     * @see #getScene()
+     * @see #sceneProperty()
+     */
     protected void setScene(Scene value) { scene.set(value); }
     public final Scene getScene() { return scene.get(); }
     public final ReadOnlyObjectProperty<Scene> sceneProperty() { return scene.getReadOnlyProperty(); }