8286678: Fix mistakes in FX API docs

Reviewed-by: kcr

Author: nlisker

modules/javafx.base/src/main/java/com/sun/javafx/collections/ObservableSetWrapper.java

@@ -321,11 +321,11 @@ public boolean addAll(Collection<?extends E> c) {
     }
 
     /**
-     * Keeps only elements that are included the specified collection.
+     * Keeps only elements that are included in the specified collection.
      * All other elements are removed. For each removed element all the
      * observers are called.
      *
-     * @see java.util.Set in JDK API documentation
+     * @see java.util.Set
      * @param c collection containing elements to be kept in this set
      * @return true if this set changed as a result of the call
      */

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

@@ -167,9 +167,8 @@ public final T get() {
     }
 
     /**
-     * The method onInvalidating() can be overridden by extending classes to
-     * react, if this binding becomes invalid. The default implementation is
-     * empty.
+     * Called when this binding becomes invalid. Can be overridden by extending classes to react to the invalidation.
+     * The default implementation is empty.
      */
     protected void onInvalidating() {
     }

modules/javafx.base/src/main/java/javafx/beans/property/Property.java

@@ -30,8 +30,7 @@
 
 /**
  * Generic interface that defines the methods common to all (writable)
- * properties independent of their type.
- *
+ * properties, independent of their type.
  *
  * @param <T>
  *            the type of the wrapped value
@@ -91,7 +90,7 @@ public interface Property<T> extends ReadOnlyProperty<T>, WritableValue<T> {
     void bindBidirectional(Property<T> other);
 
     /**
-     * Remove a bidirectional binding between this {@code Property} and another
+     * Removes a bidirectional binding between this {@code Property} and another
      * one.
      *
      * If no bidirectional binding between the properties exists, calling this
@@ -100,7 +99,7 @@ public interface Property<T> extends ReadOnlyProperty<T>, WritableValue<T> {
      * It is possible to unbind by a call on the second property. This code will work:
      *
      * <blockquote><pre>
-     *     property1.bindBirectional(property2);
+     *     property1.bindBidirectional(property2);
      *     property2.unbindBidirectional(property1);
      * </pre></blockquote>
      *

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

@@ -37,17 +37,18 @@
  * A Formatter describes a format of a {@code TextInputControl} text by using two distinct mechanisms:
  * <ul>
  *     <li>A filter ({@link #getFilter()}) that can intercept and modify user input. This helps to keep the text
- *     in the desired format. A default text supplier can be used to provide the intial text.</li>
+ *     in the desired format. A default text supplier can be used to provide the initial text.</li>
  *     <li>A value converter ({@link #getValueConverter()}) and value ({@link #valueProperty()})
  *     can be used to provide special format that represents a value of type {@code V}.
- *     If the control is editable and the text is changed by the user, the value is then updated to correspond to the text.
+ *     If the control is editable and the text is changed by the user, the value is then updated to correspond to the
+ *     text.
  * </ul>
  * <p>
- * It's possible to have a formatter with just filter or value converter. If value converter is not provided however, setting a value will
- * result in an {@code IllegalStateException} and the value is always null.
+ * It's possible to have a formatter with just a filter or a value converter. If a value converter is not provided,
+ * setting a value will result in an {@code IllegalStateException} and the value is always {@code null}.
  * <p>
- * Since {@code Formatter} contains a value which represents the state of the {@code TextInputControl} to which it is currently assigned, a single
- * {@code Formatter} instance can be used only in one {@code TextInputControl} at a time.
+ * Since {@code Formatter} contains a value that represents the state of the {@code TextInputControl} to which it is
+ * currently assigned, a single {@code Formatter} instance can be used only in one {@code TextInputControl} at a time.
  *
  * @param <V> The type of the value
  * @since JavaFX 8u40

modules/javafx.graphics/src/main/java/javafx/concurrent/ScheduledService.java

@@ -41,7 +41,7 @@
 import java.util.TimerTask;
 
 /**
- * <p>The ScheduledService is a {@link Service} which will automatically restart
+ * <p>The ScheduledService is a {@link Service} that will automatically restart
  * itself after a successful execution, and under some conditions will
  * restart even in case of failure. A new ScheduledService begins in
  * the READY state, just as a normal Service. After calling
@@ -70,7 +70,7 @@
  *
  * <p>If a failure occurs and <code>restartOnFailure</code> is false, then
  * the ScheduledService will transition to FAILED and will stop. To restart
- * a failed ScheduledService, you must call restart manually.</p>
+ * a failed ScheduledService, you must call <code>restart</code> manually.</p>
  *
  * <p>If a failure occurs and <code>restartOnFailure</code> is true, then
  * the the ScheduledService <em>may</em> restart automatically. First,
@@ -82,7 +82,7 @@
  *
  * <p>ScheduledService defines static EXPONENTIAL_BACKOFF_STRATEGY and LOGARITHMIC_BACKOFF_STRATEGY
  * implementations, of which LOGARITHMIC_BACKOFF_STRATEGY is the default value for
- * backoffStrategy. After <code>maximumFailureCount</code> is reached, the
+ * <code>backoffStrategy</code>. After <code>maximumFailureCount</code> is reached, the
  * ScheduledService will transition to FAILED in exactly the same way as if
  * <code>restartOnFailure</code> were false.</p>
  *
@@ -127,16 +127,16 @@
  * <p>For this purposes of this class, any Duration that answers true to {@link javafx.util.Duration#isUnknown()}
  * will treat that duration as if it were Duration.ZERO. Likewise, any Duration which answers true
  * to {@link javafx.util.Duration#isIndefinite()} will be treated as if it were a duration of Double.MAX_VALUE
- * milliseconds. Any null Duration is treated as Duration.ZERO. Any custom implementation of an backoff strategy
- * callback must be prepared to handle these different potential values.</p>
+ * milliseconds. Any {@code null} Duration is treated as {@code Duration.ZERO}. Any custom implementation of a backoff
+ * strategy callback must be prepared to handle these different potential values.</p>
  *
- * <p>The ScheduledService introduces a new property called {@link #lastValueProperty() lastValue}. The lastValue is the value that
- * was last successfully computed. Because a Service clears its {@code value} property on each run, and
- * because the ScheduledService will reschedule a run immediately after completion (unless it enters the
- * cancelled or failed states), the value property is not overly useful on a ScheduledService. In most cases
- * you will want to instead use the value returned by lastValue.</p>
+ * <p>The ScheduledService introduces a new property called {@link #lastValueProperty() lastValue}. The
+ * {@code lastValue} is the value that was last successfully computed. Because a Service clears its {@code value}
+ * property on each run, and because the ScheduledService will reschedule a run immediately after completion (unless it
+ * enters the cancelled or failed states), the value property is not overly useful on a ScheduledService. In most cases
+ * you will want to instead use the value returned by {@code lastValue}.</p>
  *
- * <b>Implementer Note:</b> The {@link #ready()}, {@link #scheduled()}, {@link #running()}, {@link #succeeded()},
+ * @implNote The {@link #ready()}, {@link #scheduled()}, {@link #running()}, {@link #succeeded()},
  * {@link #cancelled()}, and {@link #failed()} methods are implemented in this class. Subclasses which also
  * override these methods must take care to invoke the super implementation.
  *

modules/javafx.graphics/src/main/java/javafx/concurrent/Service.java

@@ -64,45 +64,44 @@
 
 /**
  * <p>
- *     A Service is a non-visual component encapsulating the information required
+ *     A {@code Service} is a non-visual component encapsulating the information required
  *     to perform some work on one or more background threads. As part of the
- *     JavaFX UI library, the Service knows about the JavaFX Application thread
+ *     JavaFX UI library, the {@code Service} knows about the JavaFX Application thread
  *     and is designed to relieve the application developer from the burden
  *     of managing multithreaded code that interacts with the user interface. As
- *     such, all of the methods and state on the Service are intended to be
+ *     such, all of the methods and state on the {@code Service} are intended to be
  *     invoked exclusively from the JavaFX Application thread. The only exception
- *     to this, is when initially configuring a Service, which may safely be done
- *     from any thread, and initially starting a Service, which may also safely
- *     be done from any thread. However, once the Service has been initialized and
+ *     to this is when initially configuring a {@code Service}, which may safely be done
+ *     from any thread, and initially starting a {@code Service}, which may also safely
+ *     be done from any thread. However, once the {@code Service} has been initialized and
  *     started, it may only thereafter be used from the FX thread.
  * </p>
  * <p>
- *     A Service creates and manages a {@link Task} that performs the work
+ *     A {@code Service} creates and manages a {@link Task} that performs the work
  *     on the background thread.
  *     Service implements {@link Worker}. As such, you can observe the state of
  *     the background task and optionally cancel it. Service is a reusable
- *     Worker, meaning that it can be reset and restarted. Due to this, a Service
+ *     Worker, meaning that it can be reset and restarted. Due to this, a {@code Service}
  *     can be constructed declaratively and restarted on demand.
- *     Once a Service is started, it will schedule its Task and listen for
- *     changes to the state of the Task. A Task does not hold a reference to the
- *     Service that started it, meaning that a running Task will not prevent
- *     the Service from being garbage collected.
+ *     Once a {@code Service} is started, it will schedule its {@code Task} and listen for
+ *     changes to the state of the {@code Task}. A {@code Task} does not hold a reference to the
+ *     {@code Service} that started it, meaning that a running {@code Task} will not prevent
+ *     the {@code Service} from being garbage collected.
  * </p>
  * <p>
- *     If an {@link java.util.concurrent.Executor} is specified on the Service,
+ *     If an {@link java.util.concurrent.Executor} is specified on the {@code Service},
  *     then it will be used to actually execute the service. Otherwise,
  *     a daemon thread will be created and executed. If you wish to create
- *     non-daemon threads, then specify a custom Executor (for example,
+ *     non-daemon threads, then specify a custom {@code Executor} (for example,
  *     you could use a {@link ThreadPoolExecutor} with a custom
  *     {@link java.util.concurrent.ThreadFactory}).
  * </p>
  * <p>
- *     Because a Service is intended to simplify declarative use cases, subclasses
+ *     Because a {@code Service} is intended to simplify declarative use cases, subclasses
  *     should expose as properties the input parameters to the work to be done.
- *     For example, suppose I wanted to write a Service which read the first line
- *     from any URL and returned it as a String. Such a Service might be defined,
- *     such that it had a single property, {@code url}. It might be implemented
- *     as:
+ *     For example, to write a {@code Service} that reads the first line
+ *     from any URL and returns it as a {@code String}, it might be defined with
+ *     a single property, {@code url}, and might be implemented as:
  * </p>
  *     <pre><code>
  *     {@literal public static class FirstLineService extends Service<String>} {
@@ -127,7 +126,7 @@
  *     }
  *     </code></pre>
  * <p>
- *     The Service by default uses a thread pool Executor with some unspecified
+ *     The {@code Service} by default uses a {@code ThreadPoolExecutor} with some unspecified
  *     default or maximum thread pool size. This is done so that naive code
  *     will not completely swamp the system by creating thousands of Threads.
  * </p>

modules/javafx.graphics/src/main/java/javafx/concurrent/package.html

@@ -30,10 +30,10 @@
 <html>
 <head>
   <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
-  <title>javafx.task</title>
+  <title>javafx.concurrent</title>
 </head>
 <body>
-<p>Provides the set of classes for javafx.task.</p>
+<p>Provides the set of classes for javafx.concurrent.</p>
 <p>This package provides the ability to run application code on threads other
 than the JavaFX event dispatch thread. The ability to control the execution
 and track the progress of the application code is also provided.</p>