8252389: Fix mistakes in FX API docs

Reviewed-by: aghaisas, kcr

Author: nlisker

modules/javafx.base/src/main/java/javafx/beans/binding/Bindings.java

@@ -6123,7 +6123,7 @@ public ObservableList<?> getDependencies() {
      * @param <E> the type of the {@code List} elements
      * @return the new {@code ObjectBinding}
      * @throws NullPointerException if the {@code ObservableList} is {@code null}
-     * @throws IllegalArgumentException if (@code index &lt; 0)
+     * @throws IllegalArgumentException if {@code index < 0}
      * @since JavaFX 2.1
      */
     public static <E> ObjectBinding<E> valueAt(final ObservableList<E> op, final int index) {
@@ -6230,7 +6230,7 @@ public ObservableList<?> getDependencies() {
      * @param index the position in the {@code List}
      * @return the new {@code BooleanBinding}
      * @throws NullPointerException if the {@code ObservableList} is {@code null}
-     * @throws IllegalArgumentException if (@code index &lt; 0)
+     * @throws IllegalArgumentException if {@code index < 0}
      * @since JavaFX 2.1
      */
     public static BooleanBinding booleanValueAt(final ObservableList<Boolean> op, final int index) {
@@ -6345,7 +6345,7 @@ public ObservableList<?> getDependencies() {
      * @param index the position in the {@code List}
      * @return the new {@code DoubleBinding}
      * @throws NullPointerException if the {@code ObservableList} is {@code null}
-     * @throws IllegalArgumentException if (@code index &lt; 0)
+     * @throws IllegalArgumentException if {@code index < 0}
      * @since JavaFX 2.1
      */
     public static DoubleBinding doubleValueAt(final ObservableList<? extends Number> op, final int index) {
@@ -6460,7 +6460,7 @@ public ObservableList<?> getDependencies() {
      * @param index the position in the {@code List}
      * @return the new {@code FloatBinding}
      * @throws NullPointerException if the {@code ObservableList} is {@code null}
-     * @throws IllegalArgumentException if (@code index &lt; 0)
+     * @throws IllegalArgumentException if {@code index < 0}
      * @since JavaFX 2.1
      */
     public static FloatBinding floatValueAt(final ObservableList<? extends Number> op, final int index) {
@@ -6575,7 +6575,7 @@ public ObservableList<?> getDependencies() {
      * @param index the position in the {@code List}
      * @return the new {@code IntegerBinding}
      * @throws NullPointerException if the {@code ObservableList} is {@code null}
-     * @throws IllegalArgumentException if (@code index &lt; 0)
+     * @throws IllegalArgumentException if {@code index < 0}
      * @since JavaFX 2.1
      */
     public static IntegerBinding integerValueAt(final ObservableList<? extends Number> op, final int index) {
@@ -6690,7 +6690,7 @@ public ObservableList<?> getDependencies() {
      * @param index the position in the {@code List}
      * @return the new {@code LongBinding}
      * @throws NullPointerException if the {@code ObservableList} is {@code null}
-     * @throws IllegalArgumentException if (@code index &lt; 0)
+     * @throws IllegalArgumentException if {@code index < 0}
      * @since JavaFX 2.1
      */
     public static LongBinding longValueAt(final ObservableList<? extends Number> op, final int index) {
@@ -6805,7 +6805,7 @@ public ObservableList<?> getDependencies() {
      * @param index the position in the {@code List}
      * @return the new {@code StringBinding}
      * @throws NullPointerException if the {@code ObservableList} is {@code null}
-     * @throws IllegalArgumentException if (@code index &lt; 0)
+     * @throws IllegalArgumentException if {@code index < 0}
      * @since JavaFX 2.1
      */
     public static StringBinding stringValueAt(final ObservableList<String> op, final int index) {
@@ -7070,7 +7070,7 @@ public ObservableList<?> getDependencies() {
      * @param index the position in the {@code ObservableArray}
      * @return the new {@code FloatBinding}
      * @throws NullPointerException if the {@code ObservableArray} is {@code null}
-     * @throws IllegalArgumentException if (@code index &lt; 0)
+     * @throws IllegalArgumentException if {@code index < 0}
      * @since JavaFX 8.0
      */
     public static FloatBinding floatValueAt(final ObservableFloatArray op, final int index) {
@@ -7175,7 +7175,7 @@ public ObservableList<?> getDependencies() {
      * @param index the position in the {@code ObservableArray}
      * @return the new {@code IntegerBinding}
      * @throws NullPointerException if the {@code ObservableArray} is {@code null}
-     * @throws IllegalArgumentException if (@code index &lt; 0)
+     * @throws IllegalArgumentException if {@code index < 0}
      * @since JavaFX 8.0
      */
     public static IntegerBinding integerValueAt(final ObservableIntegerArray op, final int index) {

modules/javafx.base/src/main/java/javafx/collections/ListChangeListener.java

@@ -118,7 +118,7 @@ public abstract static class Change<E> {
          * The Change instance, in its initial state, is invalid and requires a call to {@code next()} before
          * calling other methods. The first {@code next()} call will make this object
          * represent the first change.
-         * @return true if switched to the next change, false if this is the last change.
+         * @return {@code true} if switched to the next change, {@code false} if this is the last change
          */
         public abstract boolean next();
 
@@ -156,7 +156,7 @@ public ObservableList<E> getList() {
 
         /**
          * The end of the change interval.
-         * @return an end (exclusive) of an interval related to the change.
+         * @return an end (exclusive) of an interval related to the change
          * @throws IllegalStateException if this Change instance is in initial state
          * @see #getFrom()
          */
@@ -172,7 +172,7 @@ public ObservableList<E> getList() {
 
         /**
          * Indicates if the change was only a permutation.
-         * @return true if the change was just a permutation.
+         * @return {@code true} if the change was just a permutation
          * @throws IllegalStateException if this Change instance is in initial state
          */
         public boolean wasPermutated() {
@@ -181,7 +181,7 @@ public boolean wasPermutated() {
 
         /**
          * Indicates if elements were added during this change.
-         * @return true if something was added to the list
+         * @return {@code true} if something was added to the list
          * @throws IllegalStateException if this Change instance is in initial state
          */
         public boolean wasAdded() {
@@ -192,7 +192,7 @@ public boolean wasAdded() {
          * Indicates if elements were removed during this change.
          * Note that using set will also produce a change with {@code wasRemoved()} returning
          * true. See {@link #wasReplaced()}.
-         * @return true if something was removed from the list
+         * @return {@code true} if something was removed from the list
          * @throws IllegalStateException if this Change instance is in initial state
          */
         public boolean wasRemoved() {
@@ -220,7 +220,7 @@ public boolean wasReplaced() {
          * to {@link #getTo()} exclusive has changed.
          * This is the only optional event type and may not be
          * fired by all ObservableLists.
-         * @return true if the current change is an update change.
+         * @return {@code true} if the current change is an update change
          * @since JavaFX 2.1
          */
         public boolean wasUpdated() {
@@ -236,7 +236,7 @@ public boolean wasUpdated() {
          *       // do something
          * }
          * }</pre>
-         * @return the newly created sublist view that contains all the added elements.
+         * @return the newly created sublist view that contains all the added elements
          * @throws IllegalStateException if this Change instance is in initial state
          */
         public List<E> getAddedSubList() {
@@ -284,9 +284,9 @@ public int getAddedSize() {
          * Note: default implementation of this method takes the information
          * from {@link #getPermutation()} method. You don't have to override this method.
          * @param i the old index that contained the element prior to this change
+         * @return the new index of the same element
          * @throws IndexOutOfBoundsException if i is out of the bounds of the list
          * @throws IllegalStateException if this is not a permutation change
-         * @return the new index of the same element
          */
         public int getPermutation(int i) {
             if (!wasPermutated()) {

modules/javafx.controls/src/main/java/javafx/scene/control/MenuItem.java

@@ -503,24 +503,20 @@ public <E extends Event> void removeEventHandler(EventType<E> eventType, EventHa
     }
 
     /**
-     * Returns a previously set Object property, or null if no such property
-     * has been set using the {@link MenuItem#setUserData(java.lang.Object)} method.
+     * Returns the {@code Object} that was set by {@link #setUserData(Object)}, or {@code null} if no object has been
+     * set.
      *
-     * @return The Object that was previously set, or null if no property
-     *          has been set or if null was set.
+     * @return the user object that was stored (including {@code null}), or {@code null} if no object has been set
      */
     public Object getUserData() {
         return userData;
     }
 
     /**
-     * Convenience method for setting a single Object property that can be
-     * retrieved at a later date. This is functionally equivalent to calling
-     * the getProperties().put(Object key, Object value) method. This can later
-     * be retrieved by calling {@link Node#getUserData()}.
+     * Stores a user object that contains data at their discretion. It can later be retrieved by calling
+     * {@link #getUserData()}.
      *
-     * @param value The value to be stored - this can later be retrieved by calling
-     *          {@link Node#getUserData()}.
+     * @param value the user object to be stored
      */
     public void setUserData(Object value) {
         this.userData = value;

modules/javafx.controls/src/main/java/javafx/scene/control/TableFocusModel.java

@@ -27,7 +27,7 @@
 
 /**
  * The abstract base class for FocusModel implementations that are used within
- * table-like controls (most notably {@link TableView} and {@link TreeTableView}.
+ * table-like controls (most notably {@link TableView} and {@link TreeTableView}).
  *
  * @param <T> The type of the underlying data model for the UI control.
  * @param <TC> The concrete subclass of {@link TableColumnBase} that is used by the

modules/javafx.controls/src/main/java/javafx/scene/control/TableSelectionModel.java

@@ -30,7 +30,7 @@
 
 /**
  * The abstract base class for MultipleSelectionModel implementations that are used within
- * table-like controls (most notably {@link TableView} and {@link TreeTableView}.
+ * table-like controls (most notably {@link TableView} and {@link TreeTableView}).
  *
  * @param <T> The type of the underlying data model for the UI control.
  * @since JavaFX 8.0