Merge pull request #482 from twistedsquare/master

Added some documentation to some small classes

Author: JordanMartinez

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

@@ -17,6 +17,18 @@
 import javafx.scene.shape.StrokeLineCap;
 import javafx.scene.text.Text;
 
+/**
+ * A class which adds some more styleable properties to JavaFX's {@link Text} class.
+ *
+ * The extra items can be styled using the properties (and accessors/mutators) or via CSS.
+ * Each property is documented with its CSS property.  Each CSS property begins with the "-rtfx"
+ * prefix.
+ *
+ * <p>Note that the underline properties specified here are orthogonal to the {@link #underlineProperty()} inherited
+ * from {@link Text}.  The underline properties defined here in {@link TextExt} will cause an underline to be
+ * drawn if {@link #underlineWidthProperty()} is non-null and greater than zero, regardless of
+ * the value of {@link #underlineProperty()}.</p>
+ */
 public class TextExt extends Text {
 
     private final StyleableObjectProperty<Paint> backgroundColor = new StyleableObjectProperty<Paint>(null) {
@@ -133,28 +145,90 @@ public void setBackgroundColor(Paint fill) {
         backgroundColor.set(fill);
     }
 
+    /**
+     * The background color of the section of text.  By default, JavaFX doesn't
+     * support a background for Text (as it is a Shape item), but RichTextFX
+     * does support drawing a different background for different sections of text.
+     *
+     * <p>Note that this is actually a Paint type, so you can specify gradient or image fills
+     * rather than a flat colour.  But due to line wrapping, it's possible that
+     * the fill may be used multiple times on separate lines even for the same
+     * segment of text.</p>
+     *
+     * Can be styled from CSS using the "-rtfx-background-color" property.
+     */
     public ObjectProperty<Paint> backgroundColorProperty() {
         return backgroundColor;
     }
 
     // Color of the text underline (-fx-underline is already defined by JavaFX)
     public Paint getUnderlineColor() { return underlineColor.get(); }
     public void setUnderlineColor(Paint fill) { underlineColor.set(fill); }
+
+    /**
+     * The underline color of the section of text.
+     *
+     * <p>Note that this is actually a Paint type, so you can specify gradient or image fills
+     * rather than a flat colour.  But due to line wrapping, it's possible that
+     * the fill may be used multiple times on separate lines even for the
+     * same segment of text.</p>
+     *
+     * Can be styled from CSS using the "-rtfx-underline-color" property
+     * (not to be confused with JavaFX's separate "-fx-underline" property).
+     *
+     * <p>Note that the underline properties specified here are orthogonal to the {@link #underlineProperty()} inherited
+     * from {@link Text}.  The underline properties defined here in {@link TextExt} will cause an underline to be
+     * drawn if {@link #underlineWidthProperty()} is non-null and greater than zero, regardless of
+     * the value of {@link #underlineProperty()}.</p>
+     */
     public ObjectProperty<Paint> underlineColorProperty() { return underlineColor; }
 
     // Width of the text underline
     public Number getUnderlineWidth() { return underlineWidth.get(); }
     public void setUnderlineWidth(Number width) { underlineWidth.set(width); }
+
+    /**
+     * The width of the underline for a section of text.  If null or zero,
+     * the underline will not be drawn.
+     *
+     * Can be styled from CSS using the "-rtfx-underline-width" property.
+     *
+     * <p>Note that the underline properties specified here are orthogonal to the {@link #underlineProperty()} inherited
+     * from {@link Text}.  The underline properties defined here in {@link TextExt} will cause an underline to be
+     * drawn if {@link #underlineWidthProperty()} is non-null and greater than zero, regardless of
+     * the value of {@link #underlineProperty()}.</p>
+     */
     public ObjectProperty<Number> underlineWidthProperty() { return underlineWidth; }
 
     // Dash array for the text underline 
     public Number[] getUnderlineDashArray() { return underlineDashArray.get(); }
     public void setUnderlineDashArray(Number[] dashArray) { underlineDashArray.set(dashArray); }
+
+    /**
+     * The dash array used for drawing the underline for a section of text.
+     *
+     * Can be styled from CSS using the "-rtfx-underline-dash-array" property.
+     *
+     * <p>Note that the underline properties specified here are orthogonal to the {@link #underlineProperty()} inherited
+     * from {@link Text}.  The underline properties defined here in {@link TextExt} will cause an underline to be
+     * drawn if {@link #underlineWidthProperty()} is non-null and greater than zero, regardless of
+     * the value of {@link #underlineProperty()}.</p>
+     */
     public ObjectProperty<Number[]> underlineDashArrayProperty() { return underlineDashArray; }
 
     // The end cap style of each dash in a dashed underline
     public StrokeLineCap getUnderlineCap() { return underlineCap.get(); }
     public void setUnderlineCap(StrokeLineCap cap) { underlineCap.set(cap); }
+    /**
+     * The end cap style used for drawing each dash in a dashed underline for a section of text.
+     *
+     * Can be styled from CSS using the "-rtfx-underline-cap" property.
+     *
+     * <p>Note that the underline properties specified here are orthogonal to the {@link #underlineProperty()} inherited
+     * from {@link Text}.  The underline properties defined here in {@link TextExt} will cause an underline to be
+     * drawn if {@link #underlineWidthProperty()} is non-null and greater than zero, regardless of
+     * the value of {@link #underlineProperty()}.</p>
+     */
     public ObjectProperty<StrokeLineCap> underlineCapProperty() { return underlineCap; }
 
     private static class StyleableProperties {

richtextfx/src/main/java/org/fxmisc/richtext/model/Paragraph.java

@@ -13,6 +13,30 @@
 
 import org.fxmisc.richtext.model.TwoDimensional.Position;
 
+/**
+ * This is one Paragraph of the document. Depending on whether the text is wrapped,
+ * it corresponds to a single line or it can also span multiple lines. A Paragraph
+ * contains of a list of SEG objects which make up the individual segments of the
+ * Paragraph. By providing a specific segment object and an associated segment
+ * operations object, all required data and the necessary operations on this data
+ * for a single segment can be provided. For example, {@link StyledText} is a segment
+ * type which is used in {@link org.fxmisc.richtext.StyledTextArea}, a text area which can render simple
+ * text only (which is already sufficient to implement all kinds of code editors).
+ *
+ * <p>For more complex requirements (for example, when images shall be part of the
+ * document) a different segment type must be provided (which can make use of
+ * {@code StyledText<S>} for the text part and add another segment type for images).
+ * <b>Note that Paragraph is an immutable class</b> - to modify a Paragraph, a new
+ * Paragraph object must be created. Paragraph itself contains some methods which
+ * take care of this, such as concat(), which appends some Paragraph to the current
+ * one and returns a new Paragraph.</p>
+ *
+ * @param <PS> The type of the paragraph style.
+ * @param <SEG> The type of the content segments in the paragraph (e.g. {@link StyledText}).
+ *              Every paragraph, even an empty paragraph, must have at least one SEG object
+ *             (even if that SEG object itself represents an empty segment).
+ * @param <S> The type of the style of individual segments.
+ */
 public final class Paragraph<PS, SEG, S> {
 
     @SafeVarargs
@@ -166,6 +190,15 @@ public Paragraph<PS, SEG, S> delete(int start, int end) {
         return trim(start).concat(subSequence(end));
     }
 
+    /**
+     * Restyles every segment in the paragraph to have the given style.
+     *
+     * Note: because Paragraph is immutable, this method returns a new Paragraph.
+     * The current Paragraph is unchanged.
+     *
+     * @param style The new style for each segment in the paragraph.
+     * @return The new paragraph with the restyled segments.
+     */
     public Paragraph<PS, SEG, S> restyle(S style) {
         List<SEG> segs = new ArrayList<>();
         Iterator<SEG> it = segments.iterator();
@@ -218,6 +251,16 @@ public Paragraph<PS, SEG, S> restyle(int from, StyleSpans<? extends S> styleSpan
         return left.concat(newMiddle).concat(right);
     }
 
+    /**
+     * Creates a new Paragraph which has the same contents as the current Paragraph,
+     * but the given paragraph style.
+     *
+     * Note that because Paragraph is immutable, a new Paragraph is returned.
+     * Despite the setX name, the current object is unchanged.
+     *
+     * @param paragraphStyle The new paragraph style
+     * @return A new paragraph with the same segment contents, but a new paragraph style.
+     */
     public Paragraph<PS, SEG, S> setParagraphStyle(PS paragraphStyle) {
         return new Paragraph<>(paragraphStyle, segmentOps, segments);
     }
@@ -333,6 +376,10 @@ public String toString() {
                 "]";
     }
 
+    /**
+     * Two paragraphs are defined to be equal if they have the same style (as defined by
+     * PS.equals) and the same list of segments (as defined by SEG.equals).
+     */
     @Override
     public boolean equals(Object other) {
         if(other instanceof Paragraph) {

richtextfx/src/main/java/org/fxmisc/richtext/model/StyledText.java

@@ -6,8 +6,22 @@
 import java.util.Objects;
 import java.util.Optional;
 
+/**
+ * A String with a single style of type S.
+ *
+ * This is a simple class suitable for use as the SEG type in the other classes
+ * such as {@link Paragraph}, {@link org.fxmisc.richtext.GenericStyledArea}, {@link StyledDocument}, etc.
+ *
+ * This class is immutable.
+ *
+ * @param <S> The type of the style of the text.
+ */
 public class StyledText<S>  {
 
+    /**
+     * An implementation of TextOps for StyledText.  Useful for passing to the constructor
+     * of {@link org.fxmisc.richtext.GenericStyledArea} and similar classes if you are using this class as the SEG type.
+     */
     public static <S> TextOps<StyledText<S>, S> textOps() {
         return new TextOps<StyledText<S>, S>() {
 
@@ -67,6 +81,12 @@ public StyledText<S> create(String text, S style) {
         };
     }
 
+    /**
+     * A codec which allows serialisation of this class to/from a data stream.
+     *
+     * Because S may be any type, you must pass a codec for it.  If your style
+     * is String or Color, you can use {@link Codec#STRING_CODEC}/{@link Codec#COLOR_CODEC} respectively.
+     */
     public static <S> Codec<StyledText<S>> codec(Codec<S> styleCodec) {
         return new Codec<StyledText<S>>() {
 
@@ -94,15 +114,28 @@ public StyledText<S> decode(DataInputStream is) throws IOException {
 
     private final String text;
 
+    /**
+     * The text content of this piece of styled text.
+     */
     public String getText() { return text; }
 
     private final S style;
+
+    /**
+     * The style of this piece of styled text.
+     */
     public S getStyle() { return style; }
 
+    /**
+     * Creates a new StyledText with the same content but the given style.
+     */
     public StyledText<S> setStyle(S style) {
         return new StyledText<>(text, style);
     }
 
+    /**
+     * Creates a new StyledText with the given text content, and style.
+     */
     public StyledText(String text, S style) {
         this.text = text;
         this.style = style;

richtextfx/src/main/java/org/fxmisc/richtext/model/TwoDimensional.java

@@ -1,19 +1,40 @@
 package org.fxmisc.richtext.model;
 
-
+/**
+ * TwoDimensional is an interface for any item which can be navigated
+ * in two dimensions.  A two dimensional position has a major dimension
+ * (e.g. paragraph number in a document) and a minor dimension (e.g.
+ * segment index or column number within a paragraph).  Generally,
+ * documents are not rectangular (paragraphs in a document are of differing lengths),
+ * so the valid values of the minor dimension depends on the major dimension.
+ */
 public interface TwoDimensional {
 
     enum Bias {
         Forward,
         Backward,
     }
 
+    /**
+     * A two dimensional position, with a major offset (e.g. paragraph
+     * number within a document) and a minor dimension (e.g. segment index or column
+     * number within a paragraph).  Major and minor positions begin at 0.
+     */
     interface Position {
 
+        /**
+         * The TwoDimensional object that this position refers to.
+         */
         TwoDimensional getTargetObject();
 
+        /**
+         * The major dimension, e.g. paragraph number within a document
+         */
         int getMajor();
 
+        /**
+         * The minor dimension, e.g. segment index or column offset within a paragraph.
+         */
         int getMinor();
 
         /**
@@ -23,10 +44,19 @@ interface Position {
          */
         boolean sameAs(Position other);
 
+        /**
+         * Returns a new position which clamps the minor position to be valid
+         * given the major position.  (i.e. if the position is beyond the
+         * end of a given paragraph, moves the position back to the end of the paragraph).
+         */
         public Position clamp();
 
         public Position offsetBy(int offset, Bias bias);
 
+        /**
+         * Converts this position to an overall offset within the original
+         * TwoDimensional item (which getTargetObject refers to)
+         */
         int toOffset();
 
     }