From 487854cb512ca051a1691b5fe7df7d986334d437 Mon Sep 17 00:00:00 2001
From: Nir Lisker <nlisker@openjdk.org>
Date: Wed, 29 Jul 2020 09:41:54 +0000
Subject: [PATCH] 8246343: Fix mistakes in FX API docs

Reviewed-by: kcr, aghaisas
---
 .../main/java/javafx/scene/control/Cell.java  | 11 +++++---
 .../fxml/doc-files/introduction_to_fxml.html  |  2 +-
 .../java/javafx/animation/Transition.java     |  2 +-
 .../main/java/javafx/scene/layout/HBox.java   | 23 ++++++++--------
 .../main/java/javafx/scene/layout/VBox.java   | 27 ++++++++++---------
 .../src/main/java/javafx/scene/text/Text.java |  6 ++---
 6 files changed, 36 insertions(+), 35 deletions(-)

diff --git a/modules/javafx.controls/src/main/java/javafx/scene/control/Cell.java b/modules/javafx.controls/src/main/java/javafx/scene/control/Cell.java
index f2774171af2..e448cd54c4c 100644
--- a/modules/javafx.controls/src/main/java/javafx/scene/control/Cell.java
+++ b/modules/javafx.controls/src/main/java/javafx/scene/control/Cell.java
@@ -575,6 +575,7 @@ public final BooleanProperty editableProperty() {
      **************************************************************************/
 
     /**
+     * Starts an edit to the value of the cell.
      * Call this function to transition from a non-editing state into an editing
      * state, if the cell is editable. If this cell is already in an editing
      * state, it will stay in it.
@@ -586,6 +587,7 @@ public void startEdit() {
     }
 
     /**
+     * Cancels an edit to the value of the cell.
      * Call this function to transition from an editing state into a non-editing
      * state, without saving any user input.
      */
@@ -596,11 +598,12 @@ public void cancelEdit() {
     }
 
     /**
+     * Commits an edit to the value of the cell.
      * Call this function when appropriate (based on the user interaction requirements
      * of your cell editing user interface) to do two things:
      *
      * <ol>
-     *     <li>Fire the appropriate events back to the backing UI control (e.g.
+     *     <li>Fire the appropriate events back to the backing UI control (e.g.,
      *     {@link ListView}). This will begin the process of pushing this edit
      *     back to the relevant data source / property (although it does not
      *     guarantee that this will be successful - that is dependent upon the
@@ -611,12 +614,12 @@ public void cancelEdit() {
      *
      * <p>In general there is no need to override this method in custom cell
      * implementations - it should be sufficient to simply call this method
-     * when appropriate (e.g. when the user pressed the Enter key, you may do something
+     * when appropriate (e.g., when the user pressed the Enter key, you may do something
      * like {@code cell.commitEdit(converter.fromString(textField.getText()));}</p>
      *
-     * @param newValue The value as input by the end user, which should be
+     * @param newValue the value as input by the end user, which should be
      *      persisted in the relevant way given the data source underpinning the
-     *      user interface and the install edit commit handler of the UI control.
+     *      user interface and the install edit commit handler of the UI control
      */
     public void commitEdit(T newValue) {
         if (isEditing()) {
diff --git a/modules/javafx.fxml/src/main/docs/javafx/fxml/doc-files/introduction_to_fxml.html b/modules/javafx.fxml/src/main/docs/javafx/fxml/doc-files/introduction_to_fxml.html
index dc738eaf8b0..7819eec5d06 100644
--- a/modules/javafx.fxml/src/main/docs/javafx/fxml/doc-files/introduction_to_fxml.html
+++ b/modules/javafx.fxml/src/main/docs/javafx/fxml/doc-files/introduction_to_fxml.html
@@ -720,7 +720,7 @@ <h4><a id="collections_and_property_handlers">Special handlers for collections a
 <p> Collections and object properties cannot be listen to using <span class="code">setOn<span class="variable">Event</span>()</span> methods.
     For these reason, special handler methods need to be used.
 <span class="code">ObservableList</span>, <span class="code">ObservableMap</span> or <span class="code">ObservableSet</span>
- uses a special <span class="code">onChange</span> attribute that points to a handler method with a <span class="code">ListChangeListner.Change</span>, <span class="code">MapChangeListener.Change</span> or <span class="code">SetChangeListener.Change</span> parameter respectively.
+ uses a special <span class="code">onChange</span> attribute that points to a handler method with a <span class="code">ListChangeListener.Change</span>, <span class="code">MapChangeListener.Change</span> or <span class="code">SetChangeListener.Change</span> parameter, respectively.
 </p>
 <pre class="code">
 &lt;VBox fx:controller="com.foo.MyController"
diff --git a/modules/javafx.graphics/src/main/java/javafx/animation/Transition.java b/modules/javafx.graphics/src/main/java/javafx/animation/Transition.java
index 78d1e207502..cc66a5502e9 100644
--- a/modules/javafx.graphics/src/main/java/javafx/animation/Transition.java
+++ b/modules/javafx.graphics/src/main/java/javafx/animation/Transition.java
@@ -40,7 +40,7 @@
  * the implementation of a method {@link #interpolate(double)} which is the
  * called in each frame, while the {@code Transition} is running.
  * <p>
- * In addition an extending class needs to set the duration of a single cycle
+ * In addition, an extending class needs to set the duration of a single cycle
  * with {@link Animation#setCycleDuration(javafx.util.Duration)}. This duration
  * is usually set by the user via a duration property (as in
  * {@link FadeTransition#durationProperty() duration}) for example. But it can also be calculated
diff --git a/modules/javafx.graphics/src/main/java/javafx/scene/layout/HBox.java b/modules/javafx.graphics/src/main/java/javafx/scene/layout/HBox.java
index 9b02628fe8e..8356cf6bac0 100644
--- a/modules/javafx.graphics/src/main/java/javafx/scene/layout/HBox.java
+++ b/modules/javafx.graphics/src/main/java/javafx/scene/layout/HBox.java
@@ -48,8 +48,6 @@
 import javafx.geometry.HPos;
 import javafx.util.Callback;
 
-
-
 /**
  * HBox lays out its children in a single horizontal row.
  * If the hbox has a border and/or padding set, then the contents will be laid
@@ -168,13 +166,14 @@ public class HBox extends Pane {
 
     /**
      * Sets the horizontal grow priority for the child when contained by an hbox.
-     * If set, the hbox will use the priority to allocate additional space if the
-     * hbox is resized larger than it's preferred width.
+     * If set, the hbox will use the priority value to allocate additional space if the
+     * hbox is resized larger than its preferred width.
      * If multiple hbox children have the same horizontal grow priority, then the
      * extra space will be split evenly between them.
      * If no horizontal grow priority is set on a child, the hbox will never
-     * allocate it additional horizontal space if available.
-     * Setting the value to null will remove the constraint.
+     * allocate any additional horizontal space for that child.
+     * <p>
+     * Setting the value to {@code null} will remove the constraint.
      * @param child the child of an hbox
      * @param value the horizontal grow priority for the child
      */
@@ -227,14 +226,14 @@ public static void clearConstraints(Node child) {
      ********************************************************************/
 
     /**
-     * Creates an HBox layout with spacing = 0.
+     * Creates an {@code HBox} layout with {@code spacing = 0}.
      */
     public HBox() {
         super();
     }
 
     /**
-     * Creates an HBox layout with the specified spacing between children.
+     * Creates an {@code HBox} layout with the specified spacing between children.
      * @param spacing the amount of horizontal space between each child
      */
     public HBox(double spacing) {
@@ -243,8 +242,8 @@ public HBox(double spacing) {
     }
 
     /**
-     * Creates an HBox layout with spacing = 0.
-     * @param children The initial set of children for this pane.
+     * Creates an {@code HBox} layout with {@code spacing = 0}.
+     * @param children the initial set of children for this pane
      * @since JavaFX 8.0
      */
     public HBox(Node... children) {
@@ -253,9 +252,9 @@ public HBox(Node... children) {
     }
 
     /**
-     * Creates an HBox layout with the specified spacing between children.
+     * Creates an {@code HBox} layout with the specified spacing between children.
      * @param spacing the amount of horizontal space between each child
-     * @param children The initial set of children for this pane.
+     * @param children the initial set of children for this pane
      * @since JavaFX 8.0
      */
     public HBox(double spacing, Node... children) {
diff --git a/modules/javafx.graphics/src/main/java/javafx/scene/layout/VBox.java b/modules/javafx.graphics/src/main/java/javafx/scene/layout/VBox.java
index 0f02eb1fea8..9eecfe7f30f 100644
--- a/modules/javafx.graphics/src/main/java/javafx/scene/layout/VBox.java
+++ b/modules/javafx.graphics/src/main/java/javafx/scene/layout/VBox.java
@@ -154,16 +154,17 @@ public class VBox extends Pane {
     private static final String VGROW_CONSTRAINT = "vbox-vgrow";
 
     /**
-     * Sets the vertical grow priority for the child when contained by an vbox.
-     * If set, the vbox will use the priority to allocate additional space if the
-     * vbox is resized larger than it's preferred height.
+     * Sets the vertical grow priority for the child when contained by a vbox.
+     * If set, the vbox will use the priority value to allocate additional space if the
+     * vbox is resized larger than its preferred height.
      * If multiple vbox children have the same vertical grow priority, then the
      * extra space will be split evenly between them.
      * If no vertical grow priority is set on a child, the vbox will never
-     * allocate it additional vertical space if available.
-     * Setting the value to null will remove the constraint.
+     * allocate any additional vertical space for that child.
+     * <p>
+     * Setting the value to {@code null} will remove the constraint.
      * @param child the child of a vbox
-     * @param value the horizontal grow priority for the child
+     * @param value the vertical grow priority for the child
      */
     public static void setVgrow(Node child, Priority value) {
         setConstraint(child, VGROW_CONSTRAINT, value);
@@ -214,14 +215,14 @@ public static void clearConstraints(Node child) {
      ********************************************************************/
 
     /**
-     * Creates a VBox layout with spacing = 0 and alignment at TOP_LEFT.
+     * Creates a {@code VBox} layout with {@code spacing = 0} and alignment at {@code TOP_LEFT}.
      */
     public VBox() {
         super();
     }
 
     /**
-     * Creates a VBox layout with the specified spacing between children.
+     * Creates a {@code VBox} layout with the specified spacing between children.
      * @param spacing the amount of vertical space between each child
      */
     public VBox(double spacing) {
@@ -230,8 +231,8 @@ public VBox(double spacing) {
     }
 
     /**
-     * Creates an VBox layout with spacing = 0.
-     * @param children The initial set of children for this pane.
+     * Creates a {@code VBox} layout with {@code spacing = 0}.
+     * @param children the initial set of children for this pane
      * @since JavaFX 8.0
      */
     public VBox(Node... children) {
@@ -240,9 +241,9 @@ public VBox(Node... children) {
     }
 
     /**
-     * Creates an VBox layout with the specified spacing between children.
-     * @param spacing the amount of horizontal space between each child
-     * @param children The initial set of children for this pane.
+     * Creates a {@code VBox} layout with the specified spacing between children.
+     * @param spacing the amount of vertical space between each child
+     * @param children the initial set of children for this pane
      * @since JavaFX 8.0
      */
     public VBox(double spacing, Node... children) {
diff --git a/modules/javafx.graphics/src/main/java/javafx/scene/text/Text.java b/modules/javafx.graphics/src/main/java/javafx/scene/text/Text.java
index 6c1b4b4c32e..70b1bdf871a 100644
--- a/modules/javafx.graphics/src/main/java/javafx/scene/text/Text.java
+++ b/modules/javafx.graphics/src/main/java/javafx/scene/text/Text.java
@@ -795,13 +795,11 @@ public final ReadOnlyDoubleProperty baselineOffsetProperty() {
 
     /**
      * Specifies a requested font smoothing type: gray or LCD.
-     *
-     * The width of the bounding box is defined by the widest row.
-     *
+     * <p>
      * Note: LCD mode doesn't apply in numerous cases, such as various
      * compositing modes, where effects are applied and very large glyphs.
      *
-     * @defaultValue FontSmoothingType.GRAY
+     * @defaultValue {@code FontSmoothingType.GRAY}
      * @since JavaFX 2.1
      */
     private ObjectProperty<FontSmoothingType> fontSmoothingType;