8250590: Classes and methods in the javafx.css package are missing documentation

Reviewed-by: kcr, pbansal

Author: aghaisas

modules/javafx.base/src/main/java/javafx/util/StringConverter.java

@@ -43,7 +43,7 @@ public StringConverter() {
     * Converts the object provided into its string form.
     * Format of the returned string is defined by the specific converter.
     * @param object the object of type {@code T} to convert
-    * @return a string representation of the object passed in.
+    * @return a string representation of the object passed in
     */
     public abstract String toString(T object);
 

modules/javafx.graphics/src/main/java/com/sun/javafx/css/PseudoClassImpl.java

@@ -32,23 +32,38 @@
  */
 final class PseudoClassImpl extends PseudoClass {
 
-
+    /**
+     * Constructs a {@code PseudoClassImpl} object.
+     * @param pseudoClassName name of the pseudo-class
+     * @param index index of this PseudoClass in pseudoClasses list
+     * @return a {@code PseudoClassImpl} object
+     */
     PseudoClassImpl(String pseudoClassName, int index) {
         this.pseudoClassName = pseudoClassName;
         this.index = index;
     }
 
-    /** @return the pseudo-class state */
+    /**
+     * Gets the pseudo class name.
+     * @return the pseudo class name
+     */
     @Override
     public String getPseudoClassName() {
         return pseudoClassName;
     }
 
-    /** @return the pseudo-class state */
+    /**
+     * Gets the pseudo class name.
+     * @return the pseudo class name
+     */
     @Override public String toString() {
         return pseudoClassName;
     }
 
+    /**
+     * Returns the index of this {@code PseudoClass} in the styleClasses list.
+     * @return index
+     */
     public int getIndex() {
        return index;
     }

modules/javafx.graphics/src/main/java/javafx/css/CssMetaData.java

@@ -113,7 +113,7 @@
 public abstract class CssMetaData<S extends Styleable, V> {
 
     /**
-     * Set the value of the corresponding property on the given Node.
+     * Sets the value of the corresponding property on the given Node.
      * @param styleable The Styleable on which the property value is being set
      * @param value The value to which the property is set
      * @param origin the origin
@@ -160,16 +160,20 @@ public void set(S styleable, V value, StyleOrigin origin) {
     public abstract StyleableProperty<V> getStyleableProperty(S styleable);
 
     private final String property;
+
     /**
+     * Gets the CSS property name.
      * @return the CSS property name
      */
     public final String getProperty() {
         return property;
     }
 
     private final StyleConverter<?,V> converter;
+
     /**
-     * @return The CSS converter that handles conversion from a CSS value to a Java Object
+     * Gets the CSS converter that handles conversion from a CSS value to a Java Object.
+     * @return the CSS converter
      */
     public final StyleConverter<?,V> getConverter() {
         return converter;

modules/javafx.graphics/src/main/java/javafx/css/CssParser.java

@@ -107,10 +107,14 @@
 import java.util.Stack;
 
 /**
+ * A parser for a CSS document string.
  * @since 9
  */
 final public class CssParser {
 
+    /**
+     * Constructs a {@code CssParser}.
+     */
     public CssParser() {
         properties = new HashMap<String,String>();
     }
@@ -180,10 +184,10 @@ private static final class ParseException extends Exception {
     }
 
     /**
-     * Creates a stylesheet from a CSS document string.
+     * Creates a {@code Stylesheet} from a CSS document string.
      *
      * @param stylesheetText the CSS document to parse
-     * @return the Stylesheet
+     * @return the {@code Stylesheet}
      */
     public Stylesheet parse(final String stylesheetText) {
         final Stylesheet stylesheet = new Stylesheet();
@@ -199,8 +203,8 @@ public Stylesheet parse(final String stylesheetText) {
     }
 
     /**
-     * Creates a stylesheet from a CSS document string using docbase as the base
-     * URL for resolving references within stylesheet.
+     * Creates a {@code Stylesheet} from a CSS document string using docbase as the base
+     * URL for resolving references within {@code Stylesheet}.
      *
      * @param docbase the doc base for resolving URL references
      * @param stylesheetText the CSS document to parse
@@ -256,7 +260,8 @@ private void parse(final Stylesheet stylesheet, final Reader reader) {
 
     }
 
-    /** Parse an in-line style from a Node.
+    /**
+     * Parse an in-line style from a {@code Node}.
      * @param node the styleable node
      * @return the style sheet
      */
@@ -4715,23 +4720,34 @@ private Term term(CssLexer lexer) {
         return term;
     }
 
+    /**
+     * List of errors that may have occurred during CSS processing.
+     * @return an {@code ObservableList} of {@code ParseError}
+     */
     public static ObservableList<ParseError> errorsProperty() {
         return StyleManager.errorsProperty();
     }
 
 
 
     /**
-     * Encapsulate information about the source and nature of errors encountered
-     * while parsing CSS or applying styles to Nodes.
+     * A class that encapsulates information about the source and nature
+     *  of errors encountered while parsing CSS or applying styles to Nodes.
      */
     public static class ParseError {
 
-        /** @return The error message from the CSS code. */
+        /**
+         * Returns the error message.
+         * @return the error message
+         */
         public final String getMessage() {
             return message;
         }
 
+        /**
+         * Constructs a {@code ParseError} object with the message.
+         * @param message the message
+         */
         public ParseError(String message) {
             this.message = message;
         }
@@ -4815,6 +4831,12 @@ public final static class PropertySetError extends ParseError {
             private final CssMetaData styleableProperty;
             private final Styleable styleable;
 
+            /**
+             * Constructs a {@code PropertySetError} object.
+             * @param styleableProperty CSS meta data
+             * @param styleable styleable node
+             * @param message parse error message
+             */
             public PropertySetError(CssMetaData styleableProperty,
                     Styleable styleable, String message) {
                 super(message);

modules/javafx.graphics/src/main/java/javafx/css/Declaration.java

@@ -33,6 +33,7 @@
 import java.io.IOException;
 
 /**
+ * This class serves as a container of a CSS property and its value.
  * @since 9
  */
 final public class Declaration {
@@ -42,6 +43,12 @@ final public class Declaration {
     // The Rule to which this Declaration belongs.
     Rule rule;
 
+    /**
+     * Constructs a {@code Declaration} object.
+     * @param propertyName name of the CSS property
+     * @param parsedValue value of the CSS property
+     * @param important importance of the Declaration
+     */
     Declaration(final String propertyName, final ParsedValue parsedValue,
                 final boolean important) {
         this.property = propertyName;
@@ -55,26 +62,41 @@ final public class Declaration {
         }
     }
 
-    /** @return ParsedValue contains the parsed declaration. */
+    /**
+     * Gets the parsed value.
+     * @return the parsed value
+     */
     public ParsedValue getParsedValue() {
         return parsedValue;
     }
 
-    /** @return The CSS property name */
+    /**
+     * Gets the CSS property name.
+     * @return the CSS property
+     */
     public String getProperty() {
         return property;
     }
 
-    /** @return The Rule to which this Declaration belongs. */
+    /**
+     * Gets the {@code Rule} to which this {@code Declaration} belongs.
+     * @return the {@code Rule}
+     */
     public Rule getRule() {
         return rule;
     }
 
+    /**
+     * Gets the importance of this {@code Declaration}.
+     * @return the important flag
+     */
     public final boolean isImportant() {
         return important;
     }
 
-    /** Helper */
+    /**
+     * Gets the {@code StyleOrigin} of this {@code Declaration}.
+     */
     private StyleOrigin getOrigin() {
         Rule rule = getRule();
         if (rule != null)  {
@@ -83,9 +105,14 @@ private StyleOrigin getOrigin() {
         return null;
     }
     /**
-     * One declaration is the equal to another regardless of the Rule to which
-     * the Declaration belongs. Only the property, value and importance are
+     * Indicates whether some other {@code Object} is "equal to" this one.
+     * <p>
+     * One {@code Declaration} is equal to another regardless of the {@code Rule} to which
+     * the {@code Declaration} belongs. Only the property, value and importance are
      * considered.
+     *
+     * @param obj an {@code Object} to compare
+     * @return {@code true} if this object is the same as the {@code obj} argument; {@code false} otherwise
      */
     @Override public boolean equals(Object obj) {
         if (this == obj) {

modules/javafx.graphics/src/main/java/javafx/css/Match.java

@@ -65,18 +65,40 @@ public final class Match implements Comparable<Match> {
         specificity = (idCount << 8) | (styleClassCount << 4) | nPseudoClasses;
     }
 
+    /**
+     * Gets the {@code Selector}.
+     * @return the {@code Selector}
+     */
     public Selector getSelector() {
         return selector;
     }
 
+    /**
+     * Gets the pseudo class state.
+     * @return the pseudo class state
+     */
     public PseudoClassState getPseudoClasses() {
         return pseudoClasses;
     }
 
+    /**
+     * Gets the specificity.
+     * @return the specificity
+     */
     public int getSpecificity() {
         return specificity;
     }
 
+    /**
+     * Compares this object with the given {@code Match} object.
+     * <p>
+     * Comparison is based on the specificity of the objects.
+     * Specificity is calculated based on the id count, the style class count and
+     * the pseudoclass count.
+     * @param o the {@code Match} object to be compared
+     * @return the difference between the specificity of this object and
+     * the specificity of the given {@code Match} object
+     */
     @Override public int compareTo(Match o) {
         return specificity - o.specificity;
     }

modules/javafx.graphics/src/main/java/javafx/css/ParsedValue.java

@@ -47,8 +47,9 @@ public class ParsedValue<V, T> {
     final protected V value;
 
     /**
-     * @return The CSS property value as created by the parser, which may be null
+     * Gets the CSS property value as created by the parser, which may be null
      * or otherwise incomprehensible.
+     * @return the CSS property value
      */
     public final V getValue() { return value; }
 

modules/javafx.graphics/src/main/java/javafx/css/PseudoClass.java

@@ -81,18 +81,23 @@ public PseudoClass() {
     }
 
     /**
-     * There is only one PseudoClass instance for a given pseudoClass.
-     * @param pseudoClass the pseudo-class
-     * @return The PseudoClass for the given pseudoClass. Will not return null.
-     * @throws IllegalArgumentException if pseudoClass parameter is null or an empty String
+     * Gets the {@code PseudoClass} instance for a given pseudo class name.
+     * <p>
+     * Note: There is only one {@code PseudoClass} instance for a given pseudo class name.
+     *
+     * @param pseudoClass the name of the pseudo class
+     * @return the {@code PseudoClass} instance for a given pseudo class name;
+     * It will not return {@code null}
+     * @throws IllegalArgumentException if pseudoClass parameter is {@code null} or an empty {@code String}
      */
     public static PseudoClass getPseudoClass(String pseudoClass) {
-
         return PseudoClassState.getPseudoClass(pseudoClass);
-
     }
 
-    /** @return the pseudo-class state */
+    /**
+     * Gets the name of the {@code PseudoClass}.
+     * @return the name of the {@code PseudoClass}
+     */
     abstract public String getPseudoClassName();
 
 }

modules/javafx.graphics/src/main/java/javafx/css/Rule.java

@@ -40,8 +40,8 @@
 import java.util.List;
 import java.util.Set;
 
-/*
- * A selector is a collection of selectors and declarations.
+/**
+ * A Rule is a collection of CSS {@code Selector}s and {@code Declaration}s.
  *
  * @since 9
  */
@@ -135,8 +135,12 @@ public final ObservableList<Selector> getSelectors() {
         return observables.getSelectors();
     }
 
-    /** The stylesheet this selector belongs to */
     private Stylesheet stylesheet;
+
+    /**
+     * Gets the {@code Stylesheet} this {@code Rule} belongs to.
+     * @return the stylesheet
+     */
     public Stylesheet getStylesheet() {
         return stylesheet;
     }
@@ -156,6 +160,10 @@ void setStylesheet(Stylesheet stylesheet) {
         }
     }
 
+    /**
+     * Get the {@code StyleOrigin} of this {@code Stylesheet}.
+     * @return the origin of the stylesheet
+     */
     public StyleOrigin getOrigin() {
         return stylesheet != null ? stylesheet.getOrigin() : null;
     }
@@ -211,8 +219,9 @@ long applies(Node node, Set<PseudoClass>[] triggerStates) {
         return mask;
     }
 
-    /** Converts this object to a string.
-     * @return the converted string
+    /**
+     * Converts this object to a {@code String}.
+     * @return the converted {@code String}
      */
     @Override public String toString() {
         StringBuilder sb = new StringBuilder();