changeset 24494:67129b9360d2

8042120: Fix doclint warnings from javax.swing.text.html.parser Reviewed-by: alexsch Contributed-by: Alexander Stepanov <alexander.v.stepanov@oracle.com>
author yan
date Fri, 16 May 2014 17:41:47 +0400
parents 9a793dfeb09d
children a5c854a00679
files jdk/src/share/classes/javax/swing/text/html/parser/AttributeList.java jdk/src/share/classes/javax/swing/text/html/parser/ContentModel.java jdk/src/share/classes/javax/swing/text/html/parser/DTD.java jdk/src/share/classes/javax/swing/text/html/parser/Element.java jdk/src/share/classes/javax/swing/text/html/parser/Parser.java
diffstat 5 files changed, 168 insertions(+), 16 deletions(-) [+]
line wrap: on
line diff
--- a/jdk/src/share/classes/javax/swing/text/html/parser/AttributeList.java	Mon May 12 14:47:55 2014 +0200
+++ b/jdk/src/share/classes/javax/swing/text/html/parser/AttributeList.java	Fri May 16 17:41:47 2014 +0400
@@ -59,6 +59,8 @@
 
     /**
      * Create an attribute list element.
+     *
+     * @param name  the attribute name
      */
     public AttributeList(String name) {
         this.name = name;
@@ -66,6 +68,13 @@
 
     /**
      * Create an attribute list element.
+     *
+     * @param name      the attribute name
+     * @param type      the attribute type
+     * @param modifier  the attribute modifier
+     * @param value     the default attribute value
+     * @param values    the possible attribute values
+     * @param next      the next attribute in the list
      */
     public AttributeList(String name, int type, int modifier, String value, Vector<?> values, AttributeList next) {
         this.name = name;
--- a/jdk/src/share/classes/javax/swing/text/html/parser/ContentModel.java	Mon May 12 14:47:55 2014 +0200
+++ b/jdk/src/share/classes/javax/swing/text/html/parser/ContentModel.java	Fri May 16 17:41:47 2014 +0400
@@ -62,6 +62,8 @@
 
     /**
      * Create a content model for an element.
+     *
+     * @param content  the element
      */
     public ContentModel(Element content) {
         this(0, content, null);
@@ -69,6 +71,9 @@
 
     /**
      * Create a content model of a particular type.
+     *
+     * @param type     the type
+     * @param content  the content
      */
     public ContentModel(int type, ContentModel content) {
         this(type, content, null);
@@ -76,6 +81,10 @@
 
     /**
      * Create a content model of a particular type.
+     *
+     * @param type     the type
+     * @param content  the content
+     * @param next     the next content model
      */
     public ContentModel(int type, Object content, ContentModel next) {
         this.type = type;
@@ -86,6 +95,9 @@
     /**
      * Return true if the content model could
      * match an empty input stream.
+     *
+     * @return {@code true} if the content model could
+     *         match an empty input stream
      */
     public boolean empty() {
         switch (type) {
@@ -119,6 +131,8 @@
     /**
      * Update elemVec with the list of elements that are
      * part of the this contentModel.
+     *
+     * @param elemVec  the list of elements
      */
      public void getElements(Vector<Element> elemVec) {
          switch (type) {
@@ -148,6 +162,11 @@
     /**
      * Return true if the token could potentially be the
      * first token in the input stream.
+     *
+     * @param token  the token
+     *
+     * @return {@code true} if the token could potentially be the first token
+     *         in the input stream
      */
     public boolean first(Object token) {
         switch (type) {
@@ -206,6 +225,8 @@
 
     /**
      * Return the element that must be next.
+     *
+     * @return the element that must be next
      */
     public Element first() {
         switch (type) {
@@ -226,6 +247,8 @@
 
     /**
      * Convert to a string.
+     *
+     * @return the string representation of this {@code ContentModel}
      */
     public String toString() {
         switch (type) {
--- a/jdk/src/share/classes/javax/swing/text/html/parser/DTD.java	Mon May 12 14:47:55 2014 +0200
+++ b/jdk/src/share/classes/javax/swing/text/html/parser/DTD.java	Fri May 16 17:41:47 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -102,6 +102,7 @@
 
     /**
      * Gets an entity by name.
+     * @param name  the entity name
      * @return the <code>Entity</code> corresponding to the
      *   <code>name</code> <code>String</code>
      */
@@ -111,6 +112,7 @@
 
     /**
      * Gets a character entity.
+     * @param ch  the character
      * @return the <code>Entity</code> corresponding to the
      *    <code>ch</code> character
      */
@@ -193,13 +195,15 @@
      * specified parameters.  If one doesn't exist, a new
      * one is created and returned.
      *
-     * @param name the name of the <code>Element</code>
-     * @param type the type of the <code>Element</code>
-     * @param omitStart <code>true</code> if start should be omitted
-     * @param omitEnd  <code>true</code> if end should be omitted
-     * @param content  the <code>ContentModel</code>
-     * @param atts the <code>AttributeList</code> specifying the
-     *    <code>Element</code>
+     * @param name        the name of the <code>Element</code>
+     * @param type        the type of the <code>Element</code>
+     * @param omitStart   <code>true</code> if start should be omitted
+     * @param omitEnd     <code>true</code> if end should be omitted
+     * @param content     the <code>ContentModel</code>
+     * @param exclusions  the set of elements that must not occur inside the element
+     * @param inclusions  the set of elements that can occur inside the element
+     * @param atts        the <code>AttributeList</code> specifying the
+     *                    <code>Element</code>
      * @return the <code>Element</code> specified
      */
     public Element defineElement(String name, int type,
@@ -231,6 +235,8 @@
     /**
      * Creates and returns a character <code>Entity</code>.
      * @param name the entity's name
+     * @param type the entity's type
+     * @param ch   the entity's value (character)
      * @return the new character <code>Entity</code>
      */
     public Entity defEntity(String name, int type, int ch) {
@@ -241,6 +247,8 @@
     /**
      * Creates and returns an <code>Entity</code>.
      * @param name the entity's name
+     * @param type the entity's type
+     * @param str  the entity's data section
      * @return the new <code>Entity</code>
      */
     protected Entity defEntity(String name, int type, String str) {
@@ -252,7 +260,14 @@
 
     /**
      * Creates and returns an <code>Element</code>.
-     * @param name the element's name
+     * @param name        the element's name
+     * @param type        the element's type
+     * @param omitStart   {@code true} if the element needs no starting tag
+     * @param omitEnd     {@code true} if the element needs no closing tag
+     * @param content     the element's content
+     * @param exclusions  the elements that must be excluded from the content of the element
+     * @param inclusions  the elements that can be included as the content of the element
+     * @param atts        the attributes of the element
      * @return the new <code>Element</code>
      */
     protected Element defElement(String name, int type,
@@ -280,11 +295,18 @@
     }
 
     /**
-     * Creates and returns an <code>AttributeList</code>.
-     * @param name the attribute list's name
+     * Creates and returns an <code>AttributeList</code> responding to a new attribute.
+     * @param name      the attribute's name
+     * @param type      the attribute's type
+     * @param modifier  the attribute's modifier
+     * @param value     the default value of the attribute
+     * @param values    the allowed values for the attribute (multiple values could be separated by '|')
+     * @param atts      the previous attribute of the element; to be placed to {@code AttributeList.next},
+     *                  creating a linked list
      * @return the new <code>AttributeList</code>
      */
-    protected AttributeList defAttributeList(String name, int type, int modifier, String value, String values, AttributeList atts) {
+    protected AttributeList defAttributeList(String name, int type, int modifier,
+                                             String value, String values, AttributeList atts) {
         Vector<String> vals = null;
         if (values != null) {
             vals = new Vector<String>();
@@ -301,6 +323,8 @@
     /**
      * Creates and returns a new content model.
      * @param type the type of the new content model
+     * @param obj  the content of the content model
+     * @param next pointer to the next content model
      * @return the new <code>ContentModel</code>
      */
     protected ContentModel defContentModel(int type, Object obj, ContentModel next) {
@@ -332,6 +356,7 @@
      *
      * @param name the name of the DTD
      * @return the DTD which corresponds to <code>name</code>
+     * @throws IOException if an I/O error occurs
      */
     public static DTD getDTD(String name) throws IOException {
         name = name.toLowerCase();
@@ -359,6 +384,7 @@
     /**
      * Recreates a DTD from an archived format.
      * @param in  the <code>DataInputStream</code> to read from
+     * @throws IOException if an I/O error occurs
      */
     public void read(DataInputStream in) throws IOException {
         if (in.readInt() != FILE_VERSION) {
--- a/jdk/src/share/classes/javax/swing/text/html/parser/Element.java	Mon May 12 14:47:55 2014 +0200
+++ b/jdk/src/share/classes/javax/swing/text/html/parser/Element.java	Fri May 16 17:41:47 2014 +0400
@@ -64,6 +64,9 @@
 
     /**
      * Create a new element.
+     *
+     * @param name   the name of the element
+     * @param index  the index
      */
     Element(String name, int index) {
         this.name = name;
@@ -84,6 +87,8 @@
 
     /**
      * Get the name of the element.
+     *
+     * @return  the name of the element
      */
     public String getName() {
         return name;
@@ -91,6 +96,8 @@
 
     /**
      * Return true if the start tag can be omitted.
+     *
+     * @return  {@code true} if the start tag can be omitted
      */
     public boolean omitStart() {
         return oStart;
@@ -98,6 +105,8 @@
 
     /**
      * Return true if the end tag can be omitted.
+     *
+     * @return  {@code true} if the end tag can be omitted
      */
     public boolean omitEnd() {
         return oEnd;
@@ -105,6 +114,8 @@
 
     /**
      * Get type.
+     *
+     * @return  the type of the element
      */
     public int getType() {
         return type;
@@ -112,6 +123,8 @@
 
     /**
      * Get content model
+     *
+     * @return  the content model
      */
     public ContentModel getContent() {
         return content;
@@ -119,6 +132,8 @@
 
     /**
      * Get the attributes.
+     *
+     * @return  the {@code AttributeList} specifying the element
      */
     public AttributeList getAttributes() {
         return atts;
@@ -126,6 +141,8 @@
 
     /**
      * Get index.
+     *
+     * @return the element index
      */
     public int getIndex() {
         return index;
@@ -133,6 +150,8 @@
 
     /**
      * Check if empty
+     *
+     * @return  true if the current element is empty
      */
     public boolean isEmpty() {
         return type == EMPTY;
@@ -140,6 +159,8 @@
 
     /**
      * Convert to a string.
+     *
+     * @return  a string representation for the given {@code Element} instance
      */
     public String toString() {
         return name;
@@ -147,6 +168,10 @@
 
     /**
      * Get an attribute by name.
+     *
+     * @param name  the attribute name
+     *
+     * @return the {@code AttributeList} for the given {@code name}
      */
     public AttributeList getAttribute(String name) {
         for (AttributeList a = atts ; a != null ; a = a.next) {
@@ -159,10 +184,14 @@
 
     /**
      * Get an attribute by value.
+     *
+     * @param value  the string representation of value
+     *
+     * @return  the {@code AttributeList} for the given {@code value}
      */
-    public AttributeList getAttributeByValue(String name) {
+    public AttributeList getAttributeByValue(String value) {
         for (AttributeList a = atts ; a != null ; a = a.next) {
-            if ((a.values != null) && a.values.contains(name)) {
+            if ((a.values != null) && a.values.contains(value)) {
                 return a;
             }
         }
--- a/jdk/src/share/classes/javax/swing/text/html/parser/Parser.java	Mon May 12 14:47:55 2014 +0200
+++ b/jdk/src/share/classes/javax/swing/text/html/parser/Parser.java	Fri May 16 17:41:47 2014 +0400
@@ -216,6 +216,8 @@
      * the current comment tag, text, block.... This is provided for
      * subclassers that wish to know the start of the current block when
      * called with one of the handleXXX methods.
+     *
+     * @return the start position of the current block
      */
     int getBlockStartPosition() {
         return Math.max(0, lastBlockStartPos - 1);
@@ -223,31 +225,55 @@
 
     /**
      * Makes a TagElement.
+     *
+     * @param elem       the element storing the tag definition
+     * @param fictional  the value of the flag "{@code fictional}" to be set for the tag
+     *
+     * @return the created {@code TagElement}
      */
     protected TagElement makeTag(Element elem, boolean fictional) {
         return new TagElement(elem, fictional);
     }
 
+    /**
+     * Makes a TagElement.
+     *
+     * @param elem  the element storing the tag definition
+     *
+     * @return the created {@code TagElement}
+     */
     protected TagElement makeTag(Element elem) {
         return makeTag(elem, false);
     }
 
+    /**
+     * Returns attributes for the current tag.
+     *
+     * @return {@code SimpleAttributeSet} containing the attributes
+     */
     protected SimpleAttributeSet getAttributes() {
         return attributes;
     }
 
+    /**
+     * Removes the current attributes.
+     */
     protected void flushAttributes() {
         attributes.removeAttributes(attributes);
     }
 
     /**
      * Called when PCDATA is encountered.
+     *
+     * @param text  the section text
      */
     protected void handleText(char text[]) {
     }
 
     /**
      * Called when an HTML title tag is encountered.
+     *
+     * @param text  the title text
      */
     protected void handleTitle(char text[]) {
         // default behavior is to call handleText. Subclasses
@@ -257,10 +283,15 @@
 
     /**
      * Called when an HTML comment is encountered.
+     *
+     * @param text  the comment being handled
      */
     protected void handleComment(char text[]) {
     }
 
+    /**
+     * Called when the content terminates without closing the HTML comment.
+     */
     protected void handleEOFInComment() {
         // We've reached EOF.  Our recovery strategy is to
         // see if we have more than one line in the comment;
@@ -288,24 +319,34 @@
 
     /**
      * Called when an empty tag is encountered.
+     *
+     * @param tag  the tag being handled
+     * @throws ChangedCharSetException if the document charset was changed
      */
     protected void handleEmptyTag(TagElement tag) throws ChangedCharSetException {
     }
 
     /**
      * Called when a start tag is encountered.
+     *
+     * @param tag  the tag being handled
      */
     protected void handleStartTag(TagElement tag) {
     }
 
     /**
      * Called when an end tag is encountered.
+     *
+     * @param tag  the tag being handled
      */
     protected void handleEndTag(TagElement tag) {
     }
 
     /**
      * An error has occurred.
+     *
+     * @param ln   the number of line containing the error
+     * @param msg  the error message
      */
     protected void handleError(int ln, String msg) {
         /*
@@ -368,7 +409,12 @@
     }
 
     /**
-     * Invoke the error handler.
+     * Invokes the error handler.
+     *
+     * @param err   the error type
+     * @param arg1  the 1st error message argument
+     * @param arg2  the 2nd error message argument
+     * @param arg3  the 3rd error message argument
      */
     protected void error(String err, String arg1, String arg2,
         String arg3) {
@@ -390,6 +436,9 @@
      * Handle a start tag. The new tag is pushed
      * onto the tag stack. The attribute list is
      * checked for required attributes.
+     *
+     * @param tag  the tag
+     * @throws ChangedCharSetException if the document charset was changed
      */
     protected void startTag(TagElement tag) throws ChangedCharSetException {
         Element elem = tag.getElement();
@@ -441,6 +490,9 @@
     /**
      * Handle an end tag. The end tag is popped
      * from the tag stack.
+     *
+     * @param omitted  {@code true} if the tag is no actually present in the
+     *                 document, but is supposed by the parser
      */
     protected void endTag(boolean omitted) {
         handleText(stack.tag);
@@ -498,6 +550,8 @@
 
     /**
      * Marks the first time a tag has been seen in a document
+     *
+     * @param elem  the element represented by the tag
      */
 
     protected void markFirstTime(Element elem) {
@@ -1478,8 +1532,11 @@
     }
 
     /**
-     * Parses th Document Declaration Type markup declaration.
+     * Parses the Document Type Declaration markup declaration.
      * Currently ignores it.
+     *
+     * @return the string representation of the markup declaration
+     * @throws IOException if an I/O error occurs
      */
     public String parseDTDMarkup() throws IOException {
 
@@ -1523,6 +1580,11 @@
      * Parse markup declarations.
      * Currently only handles the Document Type Declaration markup.
      * Returns true if it is a markup declaration false otherwise.
+     *
+     * @param strBuff  the markup declaration
+     * @return {@code true} if this is a valid markup declaration;
+     *         otherwise {@code false}
+     * @throws IOException if an I/O error occurs
      */
     protected boolean parseMarkupDeclarations(StringBuffer strBuff) throws IOException {
 
@@ -2236,6 +2298,9 @@
 
     /**
      * Parse an HTML stream, given a DTD.
+     *
+     * @param in  the reader to read the source from
+     * @throws IOException if an I/O error occurs
      */
     public synchronized void parse(Reader in) throws IOException {
         this.in = in;