8042120: Fix doclint warnings from javax.swing.text.html.parser
Reviewed-by: alexsch
Contributed-by: Alexander Stepanov <alexander.v.stepanov@oracle.com>
--- 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;