Merge

Author: kevinrushforth

modules/javafx.base/src/main/java/javafx/beans/value/ObservableValue.java

@@ -43,7 +43,9 @@
  * this library support lazy evaluation.
  * <p>
  * An {@code ObservableValue} generates two types of events: change events and
- * invalidation events. A change event indicates that the value has changed. An
+ * invalidation events. A change event indicates that the value has changed.
+ * Current implementing classes in JavaFX check for a change using reference
+ * equality (and not object equality, {@code Object#equals(Object)}) of the value. An
  * invalidation event is generated if the current value is not valid anymore.
  * This distinction becomes important if the {@code ObservableValue} supports
  * lazy evaluation, because for a lazily evaluated value one does not know if an

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

@@ -102,22 +102,24 @@ public static <E> ObservableList<E> observableList(List<E> list) {
     }
 
     /**
-     * Constructs an ObservableList that is backed by the specified list.
-     * Mutation operations on the ObservableList instance will be reported
-     * to observers that have registered on that instance.<br>
-     * Note that mutation operations made directly to the underlying list are
-     * <em>not</em> reported to observers of any ObservableList that
+     * Constructs an {@code ObservableList} that is backed by the specified list and listens to changes in observables of its items.
+     * Mutation operations made directly to the underlying list are
+     * <em>not</em> reported to observers of any {@code ObservableList} that
      * wraps it.
-     * <br>
-     * This list also reports mutations of the elements in it by using <code>extractor</code>.
-     * Observable objects returned by extractor (applied to each list element) are listened for changes
-     * and transformed into "update" change of ListChangeListener.
+     * <p>
+     * The {@code extractor} returns observables (usually properties) of the objects in the created list. These observables are
+     * listened for changes, and the user is notified of these through an
+     * {@linkplain ListChangeListener.Change#wasUpdated() update} change of an attached {@code ListChangeListener}. These changes
+     * are unrelated to the changes made to the observable list itself using methods such as {@code add} and {@code remove}.
+     * <p>
+     * For example, a list of {@code Shape}s can listen to changes in the shapes' {@code fill} property.
      *
-     * @param <E> The type of List to be wrapped
-     * @param list a concrete List that backs this ObservableList
-     * @param extractor element to Observable[] convertor
+     * @param <E> The type of {@code List} to be wrapped
+     * @param list a concrete {@code List} that backs this {@code ObservableList}
+     * @param extractor element to {@code Observable[]} converter
+     * @return a newly created {@code ObservableList}
+     * @see #observableArrayList(javafx.util.Callback)
      * @since JavaFX 2.1
-     * @return a newly created ObservableList
      */
     public static <E> ObservableList<E> observableList(List<E> list, Callback<E, Observable[]> extractor) {
         if (list == null || extractor == null) {
@@ -307,7 +309,7 @@ public static ObservableFloatArray observableFloatArray(ObservableFloatArray arr
     }
 
     /**
-     * Creates a new empty observable list that is backed by an arraylist.
+     * Creates a new empty observable list that is backed by an array list.
      * @see #observableList(java.util.List)
      * @param <E> The type of List to be wrapped
      * @return a newly created ObservableList
@@ -318,14 +320,20 @@ public static <E> ObservableList<E> observableArrayList() {
     }
 
     /**
-     * Creates a new empty observable list backed by an arraylist.
+     * Creates a new empty {@code ObservableList} that is backed by an array list and listens to changes in observables of its items.
+     * <p>
+     * The {@code extractor} returns observables (usually properties) of the objects in the created list. These observables are
+     * listened for changes and the user is notified of these through an
+     * {@linkplain ListChangeListener.Change#wasUpdated() update} change of an attached {@code ListChangeListener}. These changes
+     * are unrelated to the changes made to the observable list itself using methods such as {@code add} and {@code remove}.
+     * <p>
+     * For example, a list of {@code Shape}s can listen to changes in the shapes' {@code fill} property.
      *
-     * This list reports element updates.
-     * @param <E> The type of List to be wrapped
-     * @param extractor element to Observable[] convertor. Observable objects are listened for changes on the element.
+     * @param <E> The type of {@code List} to be wrapped
+     * @param extractor element to {@code Observable[]} converter
+     * @return a newly created {@code ObservableList}
      * @see #observableList(java.util.List, javafx.util.Callback)
      * @since JavaFX 2.1
-     * @return a newly created ObservableList
      */
     public static <E> ObservableList<E> observableArrayList(Callback<E, Observable[]> extractor) {
         return observableList(new ArrayList(), extractor);
@@ -369,7 +377,7 @@ public static <K,V> ObservableMap<K,V> observableHashMap() {
 
     /**
      * Concatenates more observable lists into one. The resulting list
-     * would be backed by an arraylist.
+     * would be backed by an array list.
      * @param <E> The type of List to be wrapped
      * @param lists lists to concatenate
      * @return new observable array list concatenated from the arguments

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

@@ -36,7 +36,9 @@
 import javafx.collections.transformation.SortedList;
 
 /**
- * A list that allows listeners to track changes when they occur.
+ * A list that allows listeners to track changes when they occur. Implementations can be created using methods in {@link FXCollections}
+ * such as {@link FXCollections#observableArrayList() observableArrayList}, or with a
+ * {@link javafx.beans.property.SimpleListProperty SimpleListProperty}.
  *
  * @see ListChangeListener
  * @see ListChangeListener.Change

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

@@ -30,10 +30,14 @@
 import javafx.beans.Observable;
 
 /**
- * A map that allows observers to track changes when they occur.
+ * A map that allows observers to track changes when they occur. Implementations can be created using methods in {@link FXCollections}
+ * such as {@link FXCollections#observableHashMap() observableHashMap}, or with a
+ * {@link javafx.beans.property.SimpleMapProperty SimpleMapProperty}.
  *
  * @see MapChangeListener
  * @see MapChangeListener.Change
+ * @param <K> the map key element type
+ * @param <V> the map value element type
  * @since JavaFX 2.0
  */
 public interface ObservableMap<K, V> extends Map<K, V>, Observable {

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

@@ -25,16 +25,18 @@
 
 package javafx.collections;
 
-
 import java.util.Set;
 
 import javafx.beans.Observable;
 
 /**
- * A set that allows observers to track changes when they occur.
+ * A set that allows observers to track changes when they occur. Implementations can be created using methods in {@link FXCollections}
+ * such as {@link FXCollections#observableSet(Object...) observableSet}, or with a
+ * {@link javafx.beans.property.SimpleSetProperty SimpleSetProperty}.
  *
  * @see SetChangeListener
  * @see SetChangeListener.Change
+ * @param <E> the set element type
  * @since JavaFX 2.1
  */
 public interface ObservableSet<E> extends Set<E>, Observable {

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

@@ -32,8 +32,7 @@
 import javafx.util.StringConverter;
 
 /**
- * <p>{@link StringConverter} implementation for {@link Number} values
- * that represent currency.</p>
+ * A {@link StringConverter} implementation for {@link Number} values that represent currency. Instances of this class are immutable.
  *
  * @see PercentageStringConverter
  * @see NumberStringConverter
@@ -42,30 +41,54 @@
  */
 public class CurrencyStringConverter extends NumberStringConverter {
 
-    // ------------------------------------------------------------ Constructors
+    /**
+     * Constructs a {@code CurrencyStringConverter} with the default locale and format.
+     */
     public CurrencyStringConverter() {
         this(Locale.getDefault());
     }
 
+    /**
+     * Constructs a {@code CurrencyStringConverter} with the given locale and the default format.
+     *
+     * @param locale the locale used in determining the number format used to format the string
+     */
     public CurrencyStringConverter(Locale locale) {
         this(locale, null);
     }
 
+    /**
+     * Constructs a {@code CurrencyStringConverter} with the default locale and the given decimal format pattern.
+     *
+     * @param pattern the string pattern used in determining the number format used to format the string
+     *
+     * @see java.text.DecimalFormat
+     */
     public CurrencyStringConverter(String pattern) {
         this(Locale.getDefault(), pattern);
     }
 
+    /**
+     * Constructs a {@code CurrencyStringConverter} with the given locale and decimal format pattern.
+     *
+     * @param locale the locale used in determining the number format used to format the string
+     * @param pattern the string pattern used in determining the number format used to format the string
+     *
+     * @see java.text.DecimalFormat
+     */
     public CurrencyStringConverter(Locale locale, String pattern) {
         super(locale, pattern, null);
     }
 
+    /**
+     * Constructs a {@code CurrencyStringConverter} with the given number format.
+     *
+     * @param numberFormat the number format used to format the string
+     */
     public CurrencyStringConverter(NumberFormat numberFormat) {
         super(null, null, numberFormat);
     }
 
-
-    // ---------------------------------------------------------------0- Methods
-
     /** {@inheritDoc} */
     @Override protected NumberFormat getNumberFormat() {
         Locale _locale = locale == null ? Locale.getDefault() : locale;

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

@@ -33,34 +33,60 @@
 import javafx.util.StringConverter;
 
 /**
- * <p>{@link StringConverter} implementation for {@link Number} values.</p>
+ * A {@link StringConverter} implementation for {@link Number} values. Instances of this class are immutable.
+ *
  * @since JavaFX 2.1
  */
 public class NumberStringConverter extends StringConverter<Number> {
 
-    // ------------------------------------------------------ Private properties
-
     final Locale locale;
     final String pattern;
     final NumberFormat numberFormat;
 
-    // ------------------------------------------------------------ Constructors
+    /**
+     * Constructs a {@code NumberStringConverter} with the default locale and format.
+     */
     public NumberStringConverter() {
         this(Locale.getDefault());
     }
 
+    /**
+     * Constructs a {@code NumberStringConverter} with the given locale and the default format.
+     *
+     * @param locale the locale used in determining the number format used to format the string
+     */
     public NumberStringConverter(Locale locale) {
         this(locale, null);
     }
 
+    /**
+     * Constructs a {@code NumberStringConverter} with the default locale and the given decimal format pattern.
+     *
+     * @param pattern the string pattern used in determining the number format used to format the string
+     *
+     * @see java.text.DecimalFormat
+     */
     public NumberStringConverter(String pattern) {
         this(Locale.getDefault(), pattern);
     }
 
+    /**
+     * Constructs a {@code NumberStringConverter} with the given locale and decimal format pattern.
+     *
+     * @param locale the locale used in determining the number format used to format the string
+     * @param pattern the string pattern used in determining the number format used to format the string
+     *
+     * @see java.text.DecimalFormat
+     */
     public NumberStringConverter(Locale locale, String pattern) {
         this(locale, pattern, null);
     }
 
+    /**
+     * Constructs a {@code NumberStringConverter} with the given number format.
+     *
+     * @param numberFormat the number format used to format the string
+     */
     public NumberStringConverter(NumberFormat numberFormat) {
         this(null, null, numberFormat);
     }
@@ -71,8 +97,6 @@ public NumberStringConverter(NumberFormat numberFormat) {
         this.numberFormat = numberFormat;
     }
 
-    // ------------------------------------------------------- Converter Methods
-
     /** {@inheritDoc} */
     @Override public Number fromString(String value) {
         try {
@@ -112,11 +136,11 @@ public NumberStringConverter(NumberFormat numberFormat) {
     }
 
     /**
-     * <p>Return a <code>NumberFormat</code> instance to use for formatting
-     * and parsing in this {@link StringConverter}.</p>
+     * Returns a {@code NumberFormat} instance to use for formatting
+     * and parsing in this {@code StringConverter}.
      *
      * @return a {@code NumberFormat} instance for formatting and parsing in this
-     * {@link StringConverter}
+     * {@code StringConverter}
      */
     protected NumberFormat getNumberFormat() {
         Locale _locale = locale == null ? Locale.getDefault() : locale;

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

@@ -30,8 +30,8 @@
 import javafx.util.StringConverter;
 
 /**
- * <p>{@link StringConverter} implementation for {@link Number} values
- * that represent percentages.</p>
+ * A {@link StringConverter} implementation for {@link Number} values that represent percentages. Instances of this class are
+ * immutable.
  *
  * @see CurrencyStringConverter
  * @see NumberStringConverter
@@ -40,22 +40,31 @@
  */
 public class PercentageStringConverter extends NumberStringConverter {
 
-
-    // ------------------------------------------------------------ Constructors
+    /**
+     * Constructs a {@code PercentageStringConverter} with the default locale and format.
+     */
     public PercentageStringConverter() {
         this(Locale.getDefault());
     }
 
+    /**
+     * Constructs a {@code PercentageStringConverter} with the given locale and the default format.
+     *
+     * @param locale the locale used in determining the number format used to format the string
+     */
     public PercentageStringConverter(Locale locale) {
         super(locale, null, null);
     }
 
+    /**
+     * Constructs a {@code PercentageStringConverter} with the given number format.
+     *
+     * @param numberFormat the number format used to format the string
+     */
     public PercentageStringConverter(NumberFormat numberFormat) {
         super(null, null, numberFormat);
     }
 
-    // ----------------------------------------------------------------- Methods
-
     /** {@inheritDoc} */
     @Override public NumberFormat getNumberFormat() {
         Locale _locale = locale == null ? Locale.getDefault() : locale;