8228570: Add various documentation clarifications

Reviewed-by: arapte, kcr

Author: nlisker

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.controls/src/main/java/javafx/scene/control/Labeled.java

@@ -25,7 +25,6 @@
 
 package javafx.scene.control;
 
-
 import com.sun.javafx.css.StyleManager;
 import com.sun.javafx.scene.NodeHelper;
 import javafx.css.converter.BooleanConverter;
@@ -68,7 +67,6 @@
 import javafx.css.StyleableProperty;
 import javafx.css.StyleableStringProperty;
 
-
 /**
  * A Labeled {@link Control} is one which has as part of its user interface
  * a textual content associated with it. For example, a {@link Button} displays
@@ -135,7 +133,9 @@ public Labeled(String text, Node graphic) {
      **************************************************************************/
     /**
      * The text to display in the label. The text may be null.
+     *
      * @return the text to display in the label
+     * @defaultValue empty string
      */
     public final StringProperty textProperty() {
         if (text == null) {
@@ -150,7 +150,9 @@ public final StringProperty textProperty() {
     /**
      * Specifies how the text and graphic within the Labeled should be
      * aligned when there is empty space within the Labeled.
+     *
      * @return the alignment within this labeled
+     * @defaultValue {@code Pos.CENTER_LEFT}
      */
     public final ObjectProperty<Pos> alignmentProperty() {
         if (alignment == null) {
@@ -182,7 +184,9 @@ public String getName() {
      * Specifies the behavior for lines of text <em>when text is multiline</em>.
      * Unlike {@link #contentDisplayProperty} which affects the graphic and text, this setting
      * only affects multiple lines of text relative to the text bounds.
+     *
      * @return the alignment of lines of text within this labeled
+     * @defaultValue {@code TextAlignment.LEFT}
      */
     public final ObjectProperty<TextAlignment> textAlignmentProperty() {
         if (textAlignment == null) {
@@ -213,7 +217,9 @@ public String getName() {
     /**
      * Specifies the behavior to use if the text of the {@code Labeled}
      * exceeds the available space for rendering the text.
+     *
      * @return the overrun behavior if the text exceeds the available space
+     * @defaultValue {@code OverrunStyle.ELLIPSIS}
      */
     public final ObjectProperty<OverrunStyle> textOverrunProperty() {
         if (textOverrun == null) {
@@ -259,6 +265,7 @@ public String getName() {
      * @return the ellipsis property on the string to display for the ellipsis
      * when text is truncated
      * @see <a href="http://en.wikipedia.org/wiki/Ellipsis#Computer_representations">Wikipedia:ellipsis</a>
+     * @defaultValue {@code "..."}
      * @since JavaFX 2.2
      */
     public final StringProperty ellipsisStringProperty() {
@@ -287,7 +294,9 @@ public final StringProperty ellipsisStringProperty() {
     /**
      * If a run of text exceeds the width of the Labeled, then this variable
      * indicates whether the text should wrap onto another line.
+     *
      * @return the wrap property if a run of text exceeds the width of the Labeled
+     * @defaultValue {@code false}
      */
     public final BooleanProperty wrapTextProperty() {
         if (wrapText == null) {
@@ -328,7 +337,9 @@ public String getName() {
      * rich text then this font may or may not be used depending on the font
      * information embedded in the rich text, but in any case where a default
      * font is required, this font will be used.
+     *
      * @return the default font to use for text in this labeled
+     * @defaultValue {@link Font#getDefault()}
      */
     public final ObjectProperty<Font> fontProperty() {
 
@@ -403,8 +414,10 @@ public String getName() {
      * text by using {@link #setContentDisplay}.  The node specified for this
      * variable cannot appear elsewhere in the scene graph, otherwise
      * the {@code IllegalArgumentException} is thrown.  See the class
-     * description of {@link javafx.scene.Node Node} for more detail.
+     * description of {@link Node} for more detail.
+     *
      * @return the optional icon for this labeled
+     * @defaultValue {@code null}
      */
     public final ObjectProperty<Node> graphicProperty() {
         if (graphic == null) {
@@ -562,7 +575,9 @@ public CssMetaData<Labeled,String> getCssMetaData() {
 
     /**
      * Whether all text should be underlined.
+     *
      * @return the underline property of all text in this labeled
+     * @defaultValue {@code false}
      */
     public final BooleanProperty underlineProperty() {
         if (underline == null) {
@@ -592,7 +607,9 @@ public String getName() {
 
     /**
      * Specifies the space in pixel between lines.
+     *
      * @return the line spacing property between lines in this labeled
+     * @defaultValue 0
      * @since JavaFX 8.0
      */
     public final DoubleProperty lineSpacingProperty() {
@@ -623,7 +640,9 @@ public String getName() {
 
     /**
      * Specifies the positioning of the graphic relative to the text.
+     *
      * @return content display property of this labeled
+     * @defaultValue {@code ContentDisplay.LEFT}
      */
     public final ObjectProperty<ContentDisplay> contentDisplayProperty() {
         if (contentDisplay == null) {
@@ -657,7 +676,9 @@ public String getName() {
      * Subclasses may add nodes outside this padding and inside the Labeled's padding.
      *
      * This property can only be set from CSS.
-     * @return  the label padding property of this labeled
+     *
+     * @return the label padding property of this labeled
+     * @defaultValue {@code Insets.EMPTY}
      */
     public final ReadOnlyObjectProperty<Insets> labelPaddingProperty() {
         return labelPaddingPropertyImpl();
@@ -702,7 +723,9 @@ public String getName() {
 
     /**
      * The amount of space between the graphic and text
+     *
      * @return the graphics text gap property of this labeled
+     * @defaultValue 4
      */
     public final DoubleProperty graphicTextGapProperty() {
         if (graphicTextGap == null) {
@@ -733,6 +756,8 @@ public String getName() {
 
     /**
      * The {@link Paint} used to fill the text.
+     *
+     * @defaultValue {@code Color.BLACK}
      */
     private ObjectProperty<Paint> textFill; // TODO for now change this
 
@@ -776,10 +801,7 @@ public String getName() {
      * be determined based on the succeeding character, and the mnemonic
      * added.
      *
-     * <p>
-     * The default value for Labeled is false, but it
-     * is enabled by default on some Controls.
-     * </p>
+     * @defaultValue {@code false}; {@code true} for some {@code Control}s.
      */
     private BooleanProperty mnemonicParsing;
     public final void setMnemonicParsing(boolean value) {

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

@@ -57,14 +57,15 @@
  * setting the style class {@link #STYLE_CLASS_BULLET}.  The
  * {@link #maxPageIndicatorCountProperty() maxPageIndicatorCountProperty} can be used to change
  * the maximum number of page indicators.  The property value can also be changed
- * via CSS using -fx-max-page-indicator-count.
+ * via CSS using {@code -fx-max-page-indicator-count}. By default, page indicator numbering starts from 1 (corresponding to
+ * page index 0).
  *</p>
  *
  * <h2>Page count</h2>
  * <p>
  * The {@link #pageCountProperty() pageCountProperty} controls the number of
  * pages this pagination control has.  If the page count is
- * not known {@link #INDETERMINATE} should be used as the page count.
+ * not known, {@link #INDETERMINATE} should be used as the page count.
  * </p>
  *
  * <h2>Page factory</h2>
@@ -73,7 +74,7 @@
  * that is called when a page has been selected by the application or
  * the user.  The function is required for the functionality of the pagination
  * control.  The callback function should load and return the contents of the selected page.
- * Null should be returned if the selected page index does not exist.
+ * {@code null} should be returned if the selected page index does not exist.
  * </p>
  *
  * <h2>Creating a Pagination control:</h2>
@@ -86,12 +87,20 @@
  * pagination.setPageFactory(new Callback&lt;Integer, Node&gt;() {
  *     &#064;Override
  *     public Node call(Integer pageIndex) {
- *         return new Label(pageIndex+1 + ". Lorem ipsum dolor sit amet,\n"
+ *         return new Label(pageIndex + 1 + ". Lorem ipsum dolor sit amet,\n"
  *                      + "consectetur adipiscing elit,\n"
  *                      + "sed do eiusmod tempor incididunt ut\n"
  *                      + "labore et dolore magna aliqua.");
  *     }
  * });</code></pre>
+ * or using lambdas
+ * <pre><code> Pagination pagination = new Pagination(10, 0);
+ * pagination.setPageFactory(pageIndex -&gt;
+ *         new Label(pageIndex + 1 + ". Lorem ipsum dolor sit amet,\n"
+ *                      + "consectetur adipiscing elit,\n"
+ *                      + "sed do eiusmod tempor incididunt ut\n"
+ *                      + "labore et dolore magna aliqua.");
+ * );</code></pre>
  *
  * <img src="doc-files/Pagination.png" alt="Image of the Pagination control">
  *