changeset 24269:325ea76ea0e9

8042105: Fix some more doclint issues in javax.swing.text.html classes Reviewed-by: alexsch
author yan
date Thu, 08 May 2014 13:26:26 +0400
parents 43fb1c9e594c
children 12b6bc57472d
files jdk/src/share/classes/javax/swing/text/html/CSS.java jdk/src/share/classes/javax/swing/text/html/FormView.java jdk/src/share/classes/javax/swing/text/html/HTML.java jdk/src/share/classes/javax/swing/text/html/HTMLDocument.java jdk/src/share/classes/javax/swing/text/html/HTMLEditorKit.java jdk/src/share/classes/javax/swing/text/html/HTMLFrameHyperlinkEvent.java
diffstat 6 files changed, 104 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/jdk/src/share/classes/javax/swing/text/html/CSS.java	Fri Apr 25 17:19:49 2014 +0200
+++ b/jdk/src/share/classes/javax/swing/text/html/CSS.java	Thu May 08 13:26:26 2014 +0400
@@ -153,6 +153,8 @@
          * Fetch the default value for the attribute.
          * If there is no default value (such as for
          * composite attributes), null will be returned.
+         *
+         * @return default value for the attribute
          */
         public String getDefaultValue() {
             return defaultValue;
@@ -161,6 +163,8 @@
         /**
          * Indicates if the attribute should be inherited
          * from the parent or not.
+         *
+         * @return true if the attribute should be inherited from the parent
          */
         public boolean isInherited() {
             return inherited;
@@ -1036,6 +1040,8 @@
 
     /**
      * Return the set of all possible CSS attribute keys.
+     *
+     * @return the set of all possible CSS attribute keys
      */
     public static Attribute[] getAllAttributeKeys() {
         Attribute[] keys = new Attribute[Attribute.allAttributes.length];
--- a/jdk/src/share/classes/javax/swing/text/html/FormView.java	Fri Apr 25 17:19:49 2014 +0200
+++ b/jdk/src/share/classes/javax/swing/text/html/FormView.java	Thu May 08 13:26:26 2014 +0400
@@ -448,6 +448,8 @@
     /**
      * This method is responsible for submitting the form data.
      * A thread is forked to undertake the submission.
+     *
+     * @param data data to submit
      */
     protected void submitData(String data) {
         Element form = getFormElement();
--- a/jdk/src/share/classes/javax/swing/text/html/HTML.java	Fri Apr 25 17:19:49 2014 +0200
+++ b/jdk/src/share/classes/javax/swing/text/html/HTML.java	Thu May 08 13:26:26 2014 +0400
@@ -571,6 +571,9 @@
      * are recognized by the default HTML reader.
      * This set does not include tags that are
      * manufactured by the reader.
+     *
+     * @return the set of actual HTML tags that
+     * are recognized by the default HTML reader
      */
     public static Tag[] getAllTags() {
         Tag[] tags = new Tag[Tag.allTags.length];
@@ -626,6 +629,7 @@
      * @param key the key to use to fetch the value
      * @param def the default value to use if the attribute isn't
      *  defined or there is an error converting to an integer
+     * @return an attribute value
      */
     public static int getIntegerAttributeValue(AttributeSet attr,
                                                Attribute key, int def) {
--- a/jdk/src/share/classes/javax/swing/text/html/HTMLDocument.java	Fri Apr 25 17:19:49 2014 +0200
+++ b/jdk/src/share/classes/javax/swing/text/html/HTMLDocument.java	Thu May 08 13:26:26 2014 +0400
@@ -339,6 +339,7 @@
      * <p>This is a convenience method for
      * <code>getReader(int, int, int, HTML.Tag, TRUE)</code>.
      *
+     * @param pos the starting position
      * @param popDepth   the number of <code>ElementSpec.EndTagTypes</code>
      *          to generate before inserting
      * @param pushDepth  the number of <code>ElementSpec.StartTagTypes</code>
@@ -1022,6 +1023,9 @@
      * @throws IllegalArgumentException if <code>elem</code> is a leaf
      * @throws IllegalStateException if an <code>HTMLEditorKit.Parser</code>
      *         has not been defined
+     * @throws BadLocationException if replacement is impossible because of
+     *         a structural issue
+     * @throws IOException if an I/O exception occurs
      * @since 1.3
      */
     public void setInnerHTML(Element elem, String htmlText) throws
@@ -1099,6 +1103,9 @@
      * @param htmlText the string to be parsed and inserted in place of <code>elem</code>
      * @throws IllegalStateException if an HTMLEditorKit.Parser has not
      *         been set
+     * @throws BadLocationException if replacement is impossible because of
+     *         a structural issue
+     * @throws IOException if an I/O exception occurs
      * @since 1.3
      */
     public void setOuterHTML(Element elem, String htmlText) throws
@@ -1177,6 +1184,9 @@
      * @throws IllegalArgumentException if <code>elem</code> is a leaf
      * @throws IllegalStateException if an HTMLEditorKit.Parser has not
      *         been set on the document
+     * @throws BadLocationException if insertion is impossible because of
+     *         a structural issue
+     * @throws IOException if an I/O exception occurs
      * @since 1.3
      */
     public void insertAfterStart(Element elem, String htmlText) throws
@@ -1247,6 +1257,9 @@
      * @throws IllegalArgumentException if <code>elem</code> is a leaf
      * @throws IllegalStateException if an HTMLEditorKit.Parser has not
      *         been set on the document
+     * @throws BadLocationException if insertion is impossible because of
+     *         a structural issue
+     * @throws IOException if an I/O exception occurs
      * @since 1.3
      */
     public void insertBeforeEnd(Element elem, String htmlText) throws
@@ -1310,6 +1323,9 @@
      * @param htmlText the string to be parsed and inserted before <code>elem</code>
      * @throws IllegalStateException if an HTMLEditorKit.Parser has not
      *         been set on the document
+     * @throws BadLocationException if insertion is impossible because of
+     *         a structural issue
+     * @throws IOException if an I/O exception occurs
      * @since 1.3
      */
     public void insertBeforeStart(Element elem, String htmlText) throws
@@ -1368,6 +1384,9 @@
      * @param htmlText the string to be parsed and inserted after <code>elem</code>
      * @throws IllegalStateException if an HTMLEditorKit.Parser has not
      *         been set on the document
+     * @throws BadLocationException if insertion is impossible because of
+     *         a structural issue
+     * @throws IOException if an I/O exception occurs
      * @since 1.3
      */
     public void insertAfterEnd(Element elem, String htmlText) throws
@@ -1890,6 +1909,7 @@
 
         /**
          * Type of tag this iterator represents.
+         * @return the tag
          */
         public abstract HTML.Tag getTag();
     }
@@ -2171,10 +2191,24 @@
      */
     public class HTMLReader extends HTMLEditorKit.ParserCallback {
 
+        /**
+         * Constructs an HTMLReader using default pop and push depth and no tag to insert.
+         *
+         * @param offset the starting offset
+         */
         public HTMLReader(int offset) {
             this(offset, 0, 0, null);
         }
 
+        /**
+         * Constructs an HTMLReader.
+         *
+         * @param offset the starting offset
+         * @param popDepth how many parents to ascend before insert new element
+         * @param pushDepth how many parents to descend (relative to popDepth) before
+         *                  inserting
+         * @param insertTag a tag to insert (may be null)
+         */
         public HTMLReader(int offset, int popDepth, int pushDepth,
                           HTML.Tag insertTag) {
             this(offset, popDepth, pushDepth, insertTag, true, false, true);
@@ -2742,6 +2776,9 @@
          * all of the well-known tags will have been registered.
          * This can be used to change the handling of a particular
          * tag or to add support for custom tags.
+         *
+         * @param t an HTML tag
+         * @param a tag action handler
          */
         protected void registerTag(HTML.Tag t, TagAction a) {
             tagMap.put(t, a);
@@ -2762,6 +2799,9 @@
              * tag for those actions that are shared across
              * many tags.  By default this does nothing and
              * completely ignores the tag.
+             *
+             * @param t the HTML tag
+             * @param a the attributes
              */
             public void start(HTML.Tag t, MutableAttributeSet a) {
             }
@@ -2773,12 +2813,17 @@
              * tag for those actions that are shared across
              * many tags.  By default this does nothing and
              * completely ignores the tag.
+             *
+             * @param t the HTML tag
              */
             public void end(HTML.Tag t) {
             }
 
         }
 
+        /**
+         * Action assigned by default to handle the Block task of the reader.
+         */
         public class BlockAction extends TagAction {
 
             public void start(HTML.Tag t, MutableAttributeSet attr) {
@@ -2816,6 +2861,9 @@
         }
 
 
+        /**
+         * Action assigned by default to handle the Paragraph task of the reader.
+         */
         public class ParagraphAction extends BlockAction {
 
             public void start(HTML.Tag t, MutableAttributeSet a) {
@@ -2829,6 +2877,9 @@
             }
         }
 
+        /**
+         * Action assigned by default to handle the Special task of the reader.
+         */
         public class SpecialAction extends TagAction {
 
             public void start(HTML.Tag t, MutableAttributeSet a) {
@@ -2848,6 +2899,9 @@
         }
 
 
+        /**
+         * Action assigned by default to handle the Hidden task of the reader.
+         */
         public class HiddenAction extends TagAction {
 
             public void start(HTML.Tag t, MutableAttributeSet a) {
@@ -3093,6 +3147,9 @@
             }
         }
 
+        /**
+         * Action assigned by default to handle the Character task of the reader.
+         */
         public class CharacterAction extends TagAction {
 
             public void start(HTML.Tag t, MutableAttributeSet attr) {
@@ -3515,6 +3572,8 @@
          * context.  Therefore all text that is seen belongs
          * to the text area and is hence added to the
          * TextAreaDocument associated with the text area.
+         *
+         * @param data the given content
          */
         protected void textAreaContent(char[] data) {
             try {
@@ -3529,6 +3588,8 @@
          * PRE element.  This synthesizes lines to hold the
          * runs of text, and makes calls to addContent to
          * actually add the text.
+         *
+         * @param data the given content
          */
         protected void preContent(char[] data) {
             int last = 0;
@@ -3550,6 +3611,9 @@
         /**
          * Adds an instruction to the parse buffer to create a
          * block element with the given attributes.
+         *
+         * @param t an HTML tag
+         * @param attr the attribute set
          */
         protected void blockOpen(HTML.Tag t, MutableAttributeSet attr) {
             if (impliedP) {
@@ -3574,6 +3638,8 @@
         /**
          * Adds an instruction to the parse buffer to close out
          * a block element of the given type.
+         *
+         * @param t the HTML tag
          */
         protected void blockClose(HTML.Tag t) {
             inBlock--;
@@ -3672,6 +3738,9 @@
         /**
          * Adds content that is basically specified entirely
          * in the attribute set.
+         *
+         * @param t an HTML tag
+         * @param a the attribute set
          */
         protected void addSpecialElement(HTML.Tag t, MutableAttributeSet a) {
             if ((t != HTML.Tag.FRAME) && (! inParagraph) && (! inPre)) {
@@ -4049,7 +4118,13 @@
          */
         Option option;
 
+        /**
+         * Buffer to keep building elements.
+         */
         protected Vector<ElementSpec> parseBuffer = new Vector<ElementSpec>();
+        /**
+         * Current character attribute set.
+         */
         protected MutableAttributeSet charAttr = new TaggedAttributeSet();
         Stack<AttributeSet> charAttrStack = new Stack<AttributeSet>();
         Hashtable<HTML.Tag, TagAction> tagMap;
--- a/jdk/src/share/classes/javax/swing/text/html/HTMLEditorKit.java	Fri Apr 25 17:19:49 2014 +0200
+++ b/jdk/src/share/classes/javax/swing/text/html/HTMLEditorKit.java	Thu May 08 13:26:26 2014 +0400
@@ -971,6 +971,8 @@
          * Parse the given stream and drive the given callback
          * with the results of the parse.  This method should
          * be implemented to be thread-safe.
+         *
+         * @throws IOException if an I/O exception occurs
          */
         public abstract void parse(Reader r, ParserCallback cb, boolean ignoreCharSet) throws IOException;
 
@@ -1026,6 +1028,8 @@
          * or \r\n, which ever is encountered the most in parsing the
          * stream.
          *
+         * @param eol value of eol
+         *
          * @since 1.3
          */
         public void handleEndOfLineString(String eol) {
@@ -1490,6 +1494,7 @@
         }
 
         /**
+         * @param e the JEditorPane
          * @return HTMLDocument of <code>e</code>.
          */
         protected HTMLDocument getHTMLDocument(JEditorPane e) {
@@ -1501,6 +1506,7 @@
         }
 
         /**
+         * @param e the JEditorPane
          * @return HTMLEditorKit for <code>e</code>.
          */
         protected HTMLEditorKit getHTMLEditorKit(JEditorPane e) {
@@ -1514,6 +1520,10 @@
         /**
          * Returns an array of the Elements that contain <code>offset</code>.
          * The first elements corresponds to the root.
+         *
+         * @param doc an instance of HTMLDocument
+         * @param offset value of offset
+         * @return an array of the Elements that contain <code>offset</code>
          */
         protected Element[] getElementsAt(HTMLDocument doc, int offset) {
             return getElementsAt(doc.getDefaultRootElement(), offset, 0);
@@ -1541,6 +1551,11 @@
          * return -1 if no elements is found representing <code>tag</code>,
          * or 0 if the parent of the leaf at <code>offset</code> represents
          * <code>tag</code>.
+         *
+         * @param doc an instance of HTMLDocument
+         * @param offset an offset to start from
+         * @param tag tag to represent
+         * @return number of elements
          */
         protected int elementCountToTag(HTMLDocument doc, int offset,
                                         HTML.Tag tag) {
--- a/jdk/src/share/classes/javax/swing/text/html/HTMLFrameHyperlinkEvent.java	Fri Apr 25 17:19:49 2014 +0200
+++ b/jdk/src/share/classes/javax/swing/text/html/HTMLFrameHyperlinkEvent.java	Thu May 08 13:26:26 2014 +0400
@@ -125,6 +125,8 @@
 
     /**
      * returns the target for the link.
+     *
+     * @return the target for the link
      */
     public String getTarget() {
         return targetFrame;