elharo commented on code in PR #28:
URL: https://github.com/apache/xerces-j/pull/28#discussion_r2230807984
##########
src/org/apache/xerces/xni/QName.java:
##########
@@ -71,12 +72,21 @@ public QName() {
clear();
} // <init>()
- /** Constructs a QName with the specified values. */
+ /**
+ * Constructs a QName with the specified values.
+ * @param prefix the qname prefix. (e.g. "a")
+ * @param localpart the qname localpart. (e.g. "foo")
+ * @param rawname the qname rawname. (e.g. "a:foo")
+ * @param uri the URI binding. (e.g. "http://foo.com/mybinding";)
+ */
public QName(String prefix, String localpart, String rawname, String uri) {
setValues(prefix, localpart, rawname, uri);
} // <init>(String,String,String,String)
- /** Constructs a copy of the specified QName. */
+ /**
+ * Constructs a copy of the specified QName.
+ * @param qname
Review Comment:
please include a description if you're adding a param tag. The argument name
alone isn't needed.
##########
src/org/apache/html/dom/HTMLAnchorElementImpl.java:
##########
@@ -198,7 +198,7 @@ public void focus()
/**
* Constructor requires owner document.
*
- * @param owner The owner HTML document
+ * @param owner the owner HTML document
Review Comment:
this really just repeats the name of the argument in a few more words. Could
you do a global search and replace that changes this to "the HTML document in
which this element appears" or something like that?
##########
src/org/apache/xerces/xni/XMLDocumentHandler.java:
##########
@@ -78,8 +77,7 @@ public void startDocument(XMLLocator locator, String encoding,
* @param standalone The standalone value, or null if not specified.
* @param augs Additional information that may include infoset
augmentations
*
- * @exception XNIException
- * Thrown by handler to signal an error.
+ * @exception XNIException Thrown by handler to signal an error.
Review Comment:
@throws
##########
src/org/apache/xerces/xni/XMLAttributes.java:
##########
@@ -83,21 +83,22 @@ public interface XMLAttributes {
*
* @param attrIndex The attribute index.
*/
- public void removeAttributeAt(int attrIndex);
+ void removeAttributeAt(int attrIndex);
/**
- * Returns the number of attributes in the list.
+ * @return the number of attributes in the list.
Review Comment:
syntax problem. You've used an @return to replace a multiparagraph doc
comment.
##########
src/org/apache/xerces/xni/QName.java:
##########
@@ -88,7 +98,7 @@ public QName(QName qname) {
/**
* Convenience method to set the values of the qname components.
*
- * @param qname The qualified name to be copied.
+ * @param qname the qualified name to be copied.
Review Comment:
no period
##########
src/org/apache/xerces/xni/XMLAttributes.java:
##########
@@ -139,7 +140,7 @@ public interface XMLAttributes {
public void getName(int attrIndex, QName attrName);
/**
- * Returns the prefix of the attribute at the specified index.
+ * @return the prefix of the attribute at the specified index.
Review Comment:
no period in an @return that does not have a second phrase/sentence.
##########
src/org/apache/xerces/xni/Augmentations.java:
##########
@@ -73,8 +73,7 @@ public interface Augmentations {
/**
- * Returns an enumeration of the keys in the Augmentations structure
- *
+ * @return an {@link Enumeration} of the keys in the Augmentations
structure
Review Comment:
I wonder if in these cases we should have a description and an @return. Yes,
they're redundant but the process uses them for different things in the docs it
generates.
##########
src/org/apache/xerces/xni/QName.java:
##########
@@ -100,10 +110,10 @@ public void setValues(QName qname) {
/**
* Convenience method to set the values of the qname components.
*
- * @param prefix The qname prefix. (e.g. "a")
- * @param localpart The qname localpart. (e.g. "foo")
- * @param rawname The qname rawname. (e.g. "a:foo")
- * @param uri The URI binding. (e.g. "http://foo.com/mybinding";)
+ * @param prefix the qname prefix. (e.g. "a")
+ * @param localpart the qname localpart. (e.g. "foo")
Review Comment:
local part
##########
src/org/apache/xerces/xni/QName.java:
##########
@@ -125,7 +135,7 @@ public void clear() {
// Cloneable methods
//
- /** Returns a clone of this object. */
+ /** @return a clone of this object. */
Review Comment:
I may have been confusing this with the newer syntax for doing both the
return tag and the method description with one line. However, since we don't
have that you need both
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
