8046895: Fix doclint warnings in javax.swing.text.html.parser package

Reviewed-by: pchelko

jdk/src/share/classes/javax/swing/text/html/parser/AttributeList.java

@@ -47,11 +47,35 @@ import java.io.*;
 @SuppressWarnings("serial") // Same-version serialization only
 public final
 class AttributeList implements DTDConstants, Serializable {
+
+    /**
+     * The attribute name
+     */
     public String name;
+
+    /**
+     * The attribute type
+     */
     public int type;
+
+    /**
+     * The possible attribute values
+     */
     public Vector<?> values;
+
+    /**
+     * The attribute modifier
+     */
     public int modifier;
+
+    /**
+     * The default attribute value
+     */
     public String value;
+
+    /**
+     * The next attribute in the list
+     */
     public AttributeList next;
 
     AttributeList() {
@@ -171,11 +195,23 @@ class AttributeList implements DTDConstants, Serializable {
         attributeTypes.put("implied", Integer.valueOf(IMPLIED));
     }
 
+    /**
+     * Converts an attribute name to the type
+     *
+     * @param nm an attribute name
+     * @return the type
+     */
     public static int name2type(String nm) {
         Integer i = (Integer)attributeTypes.get(nm);
         return (i == null) ? CDATA : i.intValue();
     }
 
+    /**
+     * Converts a type to the attribute name
+     *
+     * @param tp a type
+     * @return the attribute name
+     */
     public static String type2name(int tp) {
         return (String)attributeTypes.get(Integer.valueOf(tp));
     }

jdk/src/share/classes/javax/swing/text/html/parser/ContentModel.java

@@ -57,6 +57,9 @@ public final class ContentModel implements Serializable {
      */
     public ContentModel next;
 
+    /**
+     * Creates {@code ContentModel}
+     */
     public ContentModel() {
     }
 

jdk/src/share/classes/javax/swing/text/html/parser/DTD.java

@@ -57,27 +57,91 @@ import java.net.URL;
  */
 public
 class DTD implements DTDConstants {
+
+    /**
+     * the name of the DTD
+     */
     public String name;
+
+    /**
+     * The vector of elements
+     */
     public Vector<Element> elements = new Vector<Element>();
+
+    /**
+     * The hash table contains the name of element and
+     * the corresponding element.
+     */
     public Hashtable<String,Element> elementHash
         = new Hashtable<String,Element>();
+
+    /**
+     * The hash table contains an {@code Object} and the corresponding {@code Entity}
+     */
     public Hashtable<Object,Entity> entityHash
         = new Hashtable<Object,Entity>();
+
+    /**
+     * The element corresponding to pcdata.
+     */
     public final Element pcdata = getElement("#pcdata");
+
+    /**
+     * The element corresponding to html.
+     */
     public final Element html = getElement("html");
+
+    /**
+     * The element corresponding to meta.
+     */
     public final Element meta = getElement("meta");
+
+    /**
+     * The element corresponding to base.
+     */
     public final Element base = getElement("base");
+
+    /**
+     * The element corresponding to isindex.
+     */
     public final Element isindex = getElement("isindex");
+
+    /**
+     * The element corresponding to head.
+     */
     public final Element head = getElement("head");
+
+    /**
+     * The element corresponding to body.
+     */
     public final Element body = getElement("body");
+
+    /**
+     * The element corresponding to applet.
+     */
     public final Element applet = getElement("applet");
+
+    /**
+     * The element corresponding to param.
+     */
     public final Element param = getElement("param");
+
+    /**
+     * The element corresponding to p.
+     */
     public final Element p = getElement("p");
+
+    /**
+     * The element corresponding to title.
+     */
     public final Element title = getElement("title");
     final Element style = getElement("style");
     final Element link = getElement("link");
     final Element script = getElement("script");
 
+    /**
+     * The version of a file
+     */
     public static final int FILE_VERSION = 1;
 
     /**
@@ -344,6 +408,12 @@ class DTD implements DTDConstants {
      */
     private static final Object DTD_HASH_KEY = new Object();
 
+    /**
+     * Put a name and appropriate DTD to hashtable.
+     *
+     * @param name the name of the DTD
+     * @param dtd the DTD
+     */
     public static void putDTDHash(String name, DTD dtd) {
         getDtdHash().put(name, dtd);
     }

jdk/src/share/classes/javax/swing/text/html/parser/DTDConstants.java

@@ -37,46 +37,186 @@ package javax.swing.text.html.parser;
 public
 interface DTDConstants {
     // Attribute value types
+
+    /**
+     * The DTD constant corresponds to CDATA
+     */
     int CDATA           = 1;
+
+    /**
+     * The DTD constant corresponds to ENTITY
+     */
     int ENTITY          = 2;
+
+    /**
+     * The DTD constant corresponds to ENTITIES
+     */
     int ENTITIES        = 3;
+
+    /**
+     * The DTD constant corresponds to ID
+     */
     int ID              = 4;
+
+    /**
+     * The DTD constant corresponds to IDREF
+     */
     int IDREF           = 5;
+
+    /**
+     * The DTD constant corresponds to IDREFS
+     */
     int IDREFS          = 6;
+
+    /**
+     * The DTD constant corresponds to NAME
+     */
     int NAME            = 7;
+
+    /**
+     * The DTD constant corresponds to NAMES
+     */
     int NAMES           = 8;
+
+    /**
+     * The DTD constant corresponds to NMTOKEN
+     */
     int NMTOKEN         = 9;
+
+    /**
+     * The DTD constant corresponds to NMTOKENS
+     */
     int NMTOKENS        = 10;
+
+    /**
+     * The DTD constant corresponds to NOTATION
+     */
     int NOTATION        = 11;
+
+    /**
+     * The DTD constant corresponds to NUMBER
+     */
     int NUMBER          = 12;
+
+    /**
+     * The DTD constant corresponds to NUMBERS
+     */
     int NUMBERS         = 13;
+
+    /**
+     * The DTD constant corresponds to NUTOKEN
+     */
     int NUTOKEN         = 14;
+
+    /**
+     * The DTD constant corresponds to NUTOKENS
+     */
     int NUTOKENS        = 15;
 
     // Content model types
+
+    /**
+     * The DTD constant corresponds to RCDATA
+     */
     int RCDATA          = 16;
+
+    /**
+     * The DTD constant corresponds to EMPTY
+     */
     int EMPTY           = 17;
+
+    /**
+     * The DTD constant corresponds to MODEL
+     */
     int MODEL           = 18;
+
+    /**
+     * The DTD constant corresponds to ANY
+     */
     int ANY             = 19;
 
     // Attribute value modifiers
+
+    /**
+     * The DTD constant corresponds to FIXED
+     */
     int FIXED           = 1;
+
+    /**
+     * The DTD constant corresponds to REQUIRED
+     */
     int REQUIRED        = 2;
+
+    /**
+     * The DTD constant corresponds to CURRENT
+     */
     int CURRENT         = 3;
+
+    /**
+     * The DTD constant corresponds to CONREF
+     */
     int CONREF          = 4;
+
+    /**
+     * The DTD constant corresponds to IMPLIED
+     */
     int IMPLIED         = 5;
 
     // Entity types
+
+    /**
+     * The DTD constant corresponds to PUBLIC
+     */
     int PUBLIC          = 10;
+
+    /**
+     * The DTD constant corresponds to SDATA
+     */
     int SDATA           = 11;
+
+    /**
+     * The DTD constant corresponds to PI
+     */
     int PI              = 12;
+
+    /**
+     * The DTD constant corresponds to STARTTAG
+     */
     int STARTTAG        = 13;
+
+    /**
+     * The DTD constant corresponds to ENDTAG
+     */
     int ENDTAG          = 14;
+
+    /**
+     * The DTD constant corresponds to MS
+     */
     int MS              = 15;
+
+    /**
+     * The DTD constant corresponds to MD
+     */
     int MD              = 16;
+
+    /**
+     * The DTD constant corresponds to SYSTEM
+     */
     int SYSTEM          = 17;
 
+    /**
+     * The DTD constant corresponds to GENERAL
+     */
+
     int GENERAL         = 1<<16;
+
+    /**
+     * The DTD constant corresponds to DEFAULT
+     */
     int DEFAULT         = 1<<17;
+
+    /**
+     * The DTD constant corresponds to PARAMETER
+     */
     int PARAMETER       = 1<<18;
 }

jdk/src/share/classes/javax/swing/text/html/parser/DocumentParser.java

@@ -112,11 +112,24 @@ public class DocumentParser extends javax.swing.text.html.parser.Parser {
     private boolean ignoreCharSet = false;
     private static final boolean debugFlag = false;
 
+    /**
+     * Creates document parser with the specified {@code dtd}.
+     *
+     * @param dtd the dtd.
+     */
     public DocumentParser(DTD dtd) {
         super(dtd);
     }
 
-    public void parse(Reader in,  HTMLEditorKit.ParserCallback callback, boolean ignoreCharSet) throws IOException {
+    /**
+     * Parse an HTML stream, given a DTD.
+     *
+     * @param in the reader to read the source from
+     * @param callback the callback
+     * @param ignoreCharSet if {@code true} the charset is ignored
+     * @throws IOException if an I/O error occurs
+     */
+    public void parse(Reader in, HTMLEditorKit.ParserCallback callback, boolean ignoreCharSet) throws IOException {
         this.ignoreCharSet = ignoreCharSet;
         this.callback = callback;
         parse(in);

jdk/src/share/classes/javax/swing/text/html/parser/Element.java

@@ -43,14 +43,50 @@ import sun.awt.AppContext;
 @SuppressWarnings("serial") // Same-version serialization only
 public final
 class Element implements DTDConstants, Serializable {
+
+    /**
+     * The element index
+     */
     public int index;
+
+    /**
+     * The name of the element
+     */
     public String name;
+
+    /**
+     * {@code true} if the start tag can be omitted
+     */
     public boolean oStart;
+
+    /**
+     * {@code true} if the end tag can be omitted
+     */
     public boolean oEnd;
+
+    /**
+     * The set of elements that can occur inside the element
+     */
     public BitSet inclusions;
+
+    /**
+     * The set of elements that must not occur inside the element
+     */
     public BitSet exclusions;
+
+    /**
+     * The element type
+     */
     public int type = ANY;
+
+    /**
+     * The content model
+     */
     public ContentModel content;
+
+    /**
+     * The attributes
+     */
     public AttributeList atts;
 
     /**
@@ -208,6 +244,14 @@ class Element implements DTDConstants, Serializable {
         contentTypes.put("ANY", Integer.valueOf(ANY));
     }
 
+    /**
+     * Converts {@code nm} to type. Returns appropriate DTDConstants
+     * if the {@code nm} is equal to CDATA, RCDATA, EMPTY or ANY, 0 otherwise.
+     *
+     * @param nm a name
+     * @return appropriate DTDConstants if the {@code nm} is equal to
+     * CDATA, RCDATA, EMPTY or ANY, 0 otherwise.
+     */
     public static int name2type(String nm) {
         Integer val = contentTypes.get(nm);
         return (val != null) ? val.intValue() : 0;

jdk/src/share/classes/javax/swing/text/html/parser/Entity.java

@@ -42,8 +42,19 @@ import java.net.URL;
  */
 public final
 class Entity implements DTDConstants {
+    /**
+     * The name of the entity.
+     */
     public String name;
+
+    /**
+     * The type of the entity.
+     */
     public int type;
+
+    /**
+     * The char array of data.
+     */
     public char data[];
 
     /**

jdk/src/share/classes/javax/swing/text/html/parser/Parser.java

@@ -88,6 +88,9 @@ class Parser implements DTDConstants {
     private char str[] = new char[128];
     private int strpos = 0;
 
+    /**
+     * The dtd.
+     */
     protected DTD dtd = null;
 
     private int ch;
@@ -198,6 +201,11 @@ class Parser implements DTDConstants {
         376    // Ÿ
     };
 
+    /**
+     * Creates parser with the specified {@code dtd}.
+     *
+     * @param dtd the dtd.
+     */
     public Parser(DTD dtd) {
         this.dtd = dtd;
     }
@@ -421,12 +429,32 @@ class Parser implements DTDConstants {
         handleError(ln, err + " " + arg1 + " " + arg2 + " " + arg3);
     }
 
+    /**
+     * Invokes the error handler with the 3rd error message argument "?".
+     *
+     * @param err   the error type
+     * @param arg1  the 1st error message argument
+     * @param arg2  the 2nd error message argument
+     */
     protected void error(String err, String arg1, String arg2) {
         error(err, arg1, arg2, "?");
     }
+
+    /**
+     * Invokes the error handler with the 2nd and 3rd error message argument "?".
+     *
+     * @param err   the error type
+     * @param arg1  the 1st error message argument
+     */
     protected void error(String err, String arg1) {
         error(err, arg1, "?", "?");
     }
+
+    /**
+     * Invokes the error handler with the 1st, 2nd and 3rd error message argument "?".
+     *
+     * @param err   the error type
+     */
     protected void error(String err) {
         error(err, "?", "?", "?");
     }
@@ -2407,6 +2435,11 @@ class Parser implements DTDConstants {
     }
 
 
+    /**
+     * Returns the current position.
+     *
+     * @return the current position
+     */
     protected int getCurrentPos() {
         return currentPosition;
     }

jdk/src/share/classes/javax/swing/text/html/parser/ParserDelegator.java

@@ -48,6 +48,9 @@ import java.security.PrivilegedAction;
 public class ParserDelegator extends HTMLEditorKit.Parser implements Serializable {
     private static final Object DTD_KEY = new Object();
 
+    /**
+     * Sets the default DTD.
+     */
     protected static void setDefaultDTD() {
         getDefaultDTD();
     }
@@ -75,6 +78,13 @@ public class ParserDelegator extends HTMLEditorKit.Parser implements Serializabl
         return dtd;
     }
 
+    /**
+     * Recreates a DTD from an archived format with the specified {@code name}.
+     *
+     * @param dtd a DTD
+     * @param name the name of the resource, relative to the  ParserDelegator class.
+     * @return the DTD with the specified {@code name}.
+     */
     protected static DTD createDTD(DTD dtd, String name) {
 
         InputStream in = null;
@@ -92,7 +102,9 @@ public class ParserDelegator extends HTMLEditorKit.Parser implements Serializabl
         return dtd;
     }
 
-
+    /**
+     * Creates {@code ParserDelegator} with default DTD.
+     */
     public ParserDelegator() {
         setDefaultDTD();
     }
@@ -109,7 +121,7 @@ public class ParserDelegator extends HTMLEditorKit.Parser implements Serializabl
      *
      * @param name the name of the resource, relative to the
      *  ParserDelegator class.
-     * @returns a stream representing the resource
+     * @return a stream representing the resource
      */
     static InputStream getResourceAsStream(final String name) {
         return AccessController.doPrivileged(

jdk/src/share/classes/javax/swing/text/html/parser/TagElement.java

@@ -39,10 +39,21 @@ public class TagElement {
     HTML.Tag htmlTag;
     boolean insertedByErrorRecovery;
 
-    public TagElement ( Element elem ) {
+    /**
+     * Creates a generic HTML TagElement class with {@code fictional} equals to {@code false}.
+     *
+     * @param elem an element
+     */
+    public TagElement(Element elem) {
         this(elem, false);
     }
 
+    /**
+     * Creates a generic HTML TagElement class.
+     *
+     * @param elem an element
+     * @param fictional if {@code true} the tag is inserted by error recovery.
+     */
     public TagElement (Element elem, boolean fictional) {
         this.elem = elem;
         htmlTag = HTML.getTag(elem.getName());
@@ -52,22 +63,52 @@ public class TagElement {
         insertedByErrorRecovery = fictional;
     }
 
+    /**
+     * Returns {@code true} if this tag causes a
+     * line break to the flow of data, otherwise returns
+     * {@code false}.
+     *
+     * @return {@code true} if this tag causes a
+     *   line break to the flow of data, otherwise returns
+     *   {@code false}
+     */
     public boolean breaksFlow() {
         return htmlTag.breaksFlow();
     }
 
+    /**
+     * Returns {@code true} if this tag is pre-formatted.
+     *
+     * @return {@code true} if this tag is pre-formatted,
+     *   otherwise returns {@code false}
+     */
     public boolean isPreformatted() {
         return htmlTag.isPreformatted();
     }
 
+    /**
+     * Returns the element.
+     *
+     * @return the element
+     */
     public Element getElement() {
         return elem;
     }
 
+    /**
+     * Returns the tag constant corresponding to the name of the {@code element}
+     *
+     * @return the tag constant corresponding to the name of the {@code element}
+     */
     public HTML.Tag getHTMLTag() {
         return htmlTag;
     }
 
+    /**
+     * Returns {@code true} if the tag is fictional.
+     *
+     * @return {@code true} if the tag is fictional.
+     */
     public boolean fictional() {
         return insertedByErrorRecovery;
     }