Cleanup javadoc; use "-rtfx" CSS prefix for caret blink rate

Author: JordanMartinez

richtextfx/src/main/java/org/fxmisc/richtext/Caret.java

@@ -36,9 +36,9 @@
 public interface Caret {
 
     /**
-     * Determines whether the caret is visible. Those who wish to use the default configuartion should use
+     * Determines whether the caret is visible. Those who wish to use the default configuration should use
      * {@link #AUTO} while those who want a more custom configuration should make a caret's {@code CaretVisibility}
-     * value oscilate between {@link #ON} and {@link #OFF}.
+     * value oscillate between {@link #ON} and {@link #OFF}.
      */
     public static enum CaretVisibility {
         /** Caret is displayed. */
@@ -209,7 +209,14 @@ default void moveSentenceBreaksBackwards(int numOfSentenceBreaks) {
      */
     public void dispose();
 
+    /**
+     * Gets the area with which this caret is associated.
+     */
     public GenericStyledArea<?, ?, ?> getArea();
 
+    /**
+     * Gets the name of this caret. Each caret that is added to an area must have a unique name since it is used
+     * to distinguish it from others in a Set.
+     */
     public String getCaretName();
 }

richtextfx/src/main/java/org/fxmisc/richtext/CaretNode.java

@@ -33,6 +33,17 @@
 import static org.reactfx.EventStreams.invalidationsOf;
 import static org.reactfx.EventStreams.merge;
 
+/**
+ * Default implementation for a {@link Caret}. Since only one {@link Path} object is used per caret, the model
+ * and view were combined into one item to grant easier access to and modification of CSS-related
+ * properties. Caution must be exercised when depending on Path-related properties in any way (e.g.
+ * {@link #boundsInLocalProperty()}, {@link #parentProperty()}, etc.). Also, {@link #caretBoundsProperty()}
+ * is distinguishable from {@link #boundsInLocalProperty()}.
+ *
+ * <p>
+ *     This class adds the css property "-rtfx-blink-rate" ({@link #blinkRateProperty()}}
+ * </p>
+ */
 public class CaretNode extends Path implements Caret, Comparable<CaretNode> {
 
     private static final javafx.util.Duration HALF_A_SECOND = javafx.util.Duration.millis(500);
@@ -57,6 +68,11 @@ public class CaretNode extends Path implements Caret, Comparable<CaretNode> {
     private final StyleableObjectProperty<javafx.util.Duration> blinkRate
             = new CustomStyleableProperty<>(HALF_A_SECOND, "blinkRate", this, BLINK_RATE);
 
+    /**
+     * The blink rate of the caret.
+     *
+     * Can be styled from CSS using the "-rtfx-blink-rate" property.
+     */
     @Override public ObjectProperty<javafx.util.Duration> blinkRateProperty() { return blinkRate; }
     @Override public javafx.util.Duration getBlinkRate() { return blinkRate.getValue(); }
     @Override public void setBlinkRate(javafx.util.Duration rate) { blinkRate.set(rate); }
@@ -359,7 +375,7 @@ private void moveContentBreaks(int numOfBreaks, BreakIterator breakIterator, boo
      * ********************************************************************** */
 
     private static final CssMetaData<CaretNode, javafx.util.Duration> BLINK_RATE
-            = new CustomCssMetaData<>("-fx-blink-rate", StyleConverter.getDurationConverter(),
+            = new CustomCssMetaData<>("-rtfx-blink-rate", StyleConverter.getDurationConverter(),
             javafx.util.Duration.millis(500), s -> s.blinkRate
     );
 

richtextfx/src/main/java/org/fxmisc/richtext/Selection.java

@@ -177,8 +177,9 @@ default void deselect() {
     }
 
     /**
-     * Configures a {@link javafx.scene.shape.Path} that will be used to render a portion or all of this selection
-     * on a given paragraph.
+     * Configures a {@link SelectionPath} that will be used to render a portion or all of this selection
+     * on a single paragraph. When the selection is a multi-paragraph selection, one path will be used
+     * to render that portion of the selection on a paragraph.
      */
     void configureSelectionPath(SelectionPath path);
 
@@ -192,6 +193,9 @@ default void deselect() {
      */
     String getSelectionName();
 
+    /**
+     * Gets the area with which this selection is associated
+     */
     GenericStyledArea<PS, SEG, S> getArea();
 
 }

richtextfx/src/main/java/org/fxmisc/richtext/SelectionImpl.java

@@ -26,6 +26,9 @@
 import static org.reactfx.EventStreams.invalidationsOf;
 import static org.reactfx.EventStreams.merge;
 
+/**
+ * Default implementation for {@link Selection}.
+ */
 public class SelectionImpl<PS, SEG, S> implements Selection<PS, SEG, S>, Comparable<SelectionImpl<PS, SEG, S>> {
 
     /* ********************************************************************** *
@@ -110,34 +113,58 @@ public class SelectionImpl<PS, SEG, S> implements Selection<PS, SEG, S>, Compara
 
     private Subscription subscription = () -> {};
 
+    /**
+     * Creates a selection with both the start and end position at 0.
+     */
     public SelectionImpl(String name, GenericStyledArea<PS, SEG, S> area) {
         this(name, area, 0, 0);
     }
 
+    /**
+     * Creates a selection with customized configuration via {@code configurePath}
+     * with both the start and end position at 0.
+     */
     public SelectionImpl(String name, GenericStyledArea<PS, SEG, S> area, Consumer<SelectionPath> configurePath) {
         this(name, area, 0, 0, area.beingUpdatedProperty(), configurePath);
     }
 
+    /**
+     * Creates a selection
+     */
     public SelectionImpl(String name, GenericStyledArea<PS, SEG, S> area, int startPosition, int endPosition) {
         this(name, area, new IndexRange(startPosition, endPosition), area.beingUpdatedProperty());
     }
 
-    public SelectionImpl(String name, GenericStyledArea<PS, SEG, S> area, int startPosition, int endPosition,
+    /**
+     * Creates a selection that is to be used in a {@link CaretSelectionBind}.
+     */
+    SelectionImpl(String name, GenericStyledArea<PS, SEG, S> area, int startPosition, int endPosition,
                          SuspendableNo dependentBeingUpdated) {
         this(name, area, new IndexRange(startPosition, endPosition), dependentBeingUpdated);
     }
 
-    public SelectionImpl(String name, GenericStyledArea<PS, SEG, S> area, int startPosition, int endPosition,
+    /**
+     * Creates a selection that is to be used in a {@link CaretSelectionBind} with customized configuration.
+     */
+    SelectionImpl(String name, GenericStyledArea<PS, SEG, S> area, int startPosition, int endPosition,
                          SuspendableNo dependentBeingUpdated, Consumer<SelectionPath> configurePath) {
         this(name, area, new IndexRange(startPosition, endPosition), dependentBeingUpdated, configurePath);
     }
 
-    public SelectionImpl(String name, GenericStyledArea<PS, SEG, S> area, IndexRange range,
+    /**
+     * Creates a selection that is to be used in a {@link CaretSelectionBind}. It adds the style class
+     * {@code selection} to any {@link SelectionPath} used to render this selection.
+     */
+    SelectionImpl(String name, GenericStyledArea<PS, SEG, S> area, IndexRange range,
                          SuspendableNo dependentBeingUpdated) {
         this(name, area, range, dependentBeingUpdated, path -> path.getStyleClass().add("selection"));
     }
 
-    public SelectionImpl(String name, GenericStyledArea<PS, SEG, S> area, IndexRange range,
+    /**
+     * Creates a selection that is to be used in a {@link CaretSelectionBind}
+     * with customized configuration and starting at the given range.
+     */
+    SelectionImpl(String name, GenericStyledArea<PS, SEG, S> area, IndexRange range,
                          SuspendableNo dependentBeingUpdated, Consumer<SelectionPath> configurePath) {
         this.name = name;
         this.area = area;

richtextfx/src/main/java/org/fxmisc/richtext/SelectionPath.java

@@ -1,5 +1,6 @@
 package org.fxmisc.richtext;
 
+import javafx.beans.property.ObjectProperty;
 import javafx.css.CssMetaData;
 import javafx.css.StyleConverter;
 import javafx.css.Styleable;
@@ -15,16 +16,18 @@
 import java.util.List;
 
 /**
- * A class for a path which describes a selection shape in the Scene graph; it does not have a style class
- * associated with it.
+ * A Path used to render a portion of a mulit-paragraph selection or all of a single-paragraph selection
+ * with additional CSS styling; it does not have a style class associated with it.
  */
 public class SelectionPath extends Path {
 
-    /**
-     * Background fill for highlighted text.
-     */
     private final StyleableObjectProperty<Paint> highlightFill
             = new CustomStyleableProperty<>(Color.DODGERBLUE, "highlightFill", this, HIGHLIGHT_FILL);
+
+    /**
+     * Background fill for highlighted/selected text. Can be styled using "-fx-highlight-fill".
+     */
+    public final ObjectProperty<Paint> highlightFillProperty() { return highlightFill; }
     public final Paint getHighlightFill() { return highlightFill.get(); }
     public final void setHighlightFill(Paint paint) { highlightFill.set(paint); }
 

richtextfx/src/main/resources/org/fxmisc/richtext/styled-text-area.css

@@ -7,7 +7,7 @@
 }
 
 .styled-text-area .caret {
-    -fx-blink-rate: 500ms;
+    -rtfx-blink-rate: 500ms;
     -fx-stroke-width: 1.0;
 }