Re: [PR] [XERCESJ-1781] fix Javadoc warnings [xerces-j ]

elharo commented on code in PR #48:
URL: https://github.com/apache/xerces-j/pull/48#discussion_r2533790727


##########
src/org/apache/xerces/xs/datatypes/XSDateTime.java:
##########
@@ -205,57 +205,68 @@
 public interface XSDateTime {
 	
     /**
+     * Returns years.

Review Comment:
   It's also OK to just not add any description for these sorts of things in this PR, and someone can come back to them later. 



##########
src/org/apache/xerces/xs/datatypes/XSDateTime.java:
##########
@@ -266,23 +286,29 @@ public interface XSDateTime {
     
     /**
      * @return a new date-time related object with normalized values
-     *         (has no effect on objects already
-     *          normalized)
+     *         (has no effect on objects already normalized)
      */
     public XSDateTime normalize();
     
     /**
+     * Returns whether a date-time related object is normalized or not.
+     * This is only useful for datetimes that have timezone
+     *
      * @return whether a date-time related object is normalized or not
      *         (value is not useful for types where timezone is not specified)
      */
     public boolean isNormalized();
        
     /**
+     * Returns an un-normalized XMLGregorianCalendar or null.
+     *
      * @return an un-normalized XMLGregorianCalendar (if applicable otherwise null)
      */
     public XMLGregorianCalendar getXMLGregorianCalendar();
         
     /**
+     * Returns the duration if applicable otherwise null.

Review Comment:
   comma after applicable
   
   But again this just dupes the return tag text, so it's not super helpful and I'm inclined to leave it out. What would be helpful would be better explaining what "applicable" means here. That is, under what circumstances does this return null? That would add to what's already in the return tag.
   
   Of course, you don't have to do this here. It's not reasonable or good to rewrite every doc comment in one PR. But it might be better to leave out the body text instead of duplicating what's already there since it makes both code and docs shorter and easier to read and fits more useful content on one screen.
   
   Leaving the warning in for now would mean this would be more likely to get some attention in the future when someone has time to write a more complete description



-- 
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]