Re: RFR (JAXP): 8021787: javax.xml.datatype.XMLGregorianCalendar.getMonth() return is documented wrong

Thu, 21 Jul 2016 09:34:57 -0700

The editor of the new version of Thunderbird seems to be troublesome, with missing or added whitespace as a result of copy&paste. But when you "@return the hour of dayof this", you know I meant "@return the hour of day of this" :-) Or the double whitespace should have been a single one. 

-Joe

On 7/21/2016 9:25 AM, huizhe wang wrote:

Hi Svetlana,
It would be good to apply the same format to these get* methods. Please see below. 

@@ -510,16 +510,16 @@
          * @see #getYear()
          */
         public abstract BigInteger getEonAndYear();

         /**
- * Return number of month or {@link DatatypeConstants#FIELD_UNDEFINED}.
+ * Returns the month of this calendar or {@link DatatypeConstants#FIELD_UNDEFINED}. 
          * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-month">month field of date/time field mapping table</a>. 
          *
- * @return year of this {@code XMLGregorianCalendar}.
+ * @return Returns the month of this {@code XMLGregorianCalendar}.

remove the duplicated "Returns", that is

@return the month  of the{@code XMLGregorianCalendar}, from 1 to 12.


          */
         public abstract int getMonth();

         /**

------------------------------------------------------------------------

@@ -526,10 +526,12 @@
* Return day in month or {@link DatatypeConstants#FIELD_UNDEFINED}. 

Returns the day of month

          * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-day">day field of date/time field mapping table</a>. 
          *
+ * @return Day in month of this {@code XMLGregorianCalendar}.
@return the day of month of the{@code XMLGregorianCalendar}, from 1 to 31. 


+ *
          * @see #setDay(int)
          */
         public abstract int getDay();

         /**

------------------------------------------------------------------------

@@ -537,10 +539,12 @@
* {@link DatatypeConstants#FIELD_UNDEFINED} if this optional field is not defined. 

Returns the Timezone offset...

          * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-timezone">timezone field of date/time field mapping table</a>. 
          *
+ * @return Timezone offset in minutes of this {@code XMLGregorianCalendar}. 

@return the Timezone ...

 + *
          * @see #setTimezone(int)
          */
         public abstract int getTimezone();

         /**

------------------------------------------------------------------------

@@ -547,10 +551,13 @@
          * Return hours or {@link DatatypeConstants#FIELD_UNDEFINED}.

Returns the hour of day
* Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. 
          *
          * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-hour">hour field of date/time field mapping table</a>. 
+ *
+ * @return Hours of this {@code XMLGregorianCalendar}.
@return the hour of dayof this {@code XMLGregorianCalendar}, from 0 to 23. 

 + *
          * @see #setTime(int, int, int)
          */
         public abstract int getHour();

         /**

------------------------------------------------------------------------

@@ -557,10 +564,13 @@
          * Return minutes or {@link DatatypeConstants#FIELD_UNDEFINED}.

Returns the minute of hour...
* Returns {@link DatatypeConstants#FIELD_UNDEFINED} if this field is not defined. 
          *
          * <p>Value constraints for this value are summarized in
* <a href="#datetimefield-minute">minute field of date/time field mapping table</a>. 
+ *
+ * @return Minutes of this {@code XMLGregorianCalendar}.
@return the minute of hourof this {@code XMLGregorianCalendar}, from 0 to 59. 

+ *
          * @see #setTime(int, int, int)
          */
         public abstract int getMinute();

         /**

------------------------------------------------------------------------

@@ -679,10 +689,11 @@
      * {@code XMLGregorianCalendar} and
      * {@link #compare(XMLGregorianCalendar obj)}
      * returns {@link DatatypeConstants#EQUAL},
      * otherwise {@code false}.
      */
+ @Override
     public boolean equals(Object obj) {

         if (obj == null || !(obj instanceof XMLGregorianCalendar)) {
                return false;
         }

------------------------------------------------------------------------

@@ -692,10 +703,11 @@
     /**
* Returns a hash code consistent with the definition of the equals method. 
      *
      * @return hash code of this object.
      */
+ @Override
     public int hashCode() {
// Following two dates compare to EQUALS since in different timezones. 
         // 2000-01-15T12:00:00-05:00 == 2000-01-15T13:00:00-04:00
         //

------------------------------------------------------------------------

@@ -853,13 +865,13 @@
          *
* @return A non-{@code null} valid {@code String} representation of this {@code XMLGregorianCalendar}. 
          *
      * @throws IllegalStateException if the combination of set fields
* does not match one of the eight defined XML Schema builtin date/time datatypes. 
- *
      * @see #toXMLFormat()
          */
+ @Override
     public String toString() {

         return toXMLFormat();
     }


------------------------------------------------------------------------

@@ -968,10 +980,12 @@
      *   <li>Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY,
      *       MINUTE, SECOND and MILLISECOND are set using the method
      *       {@code Calendar.set(int,int)}</li>
      * </ul>
      *
+ * @return a {@code java.util.GregorianCalendar} conversion of this instance. 

@return an instance of{@link java.util.GregorianCalendar}.

+ *
* @see #toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar) 
      */
     public abstract GregorianCalendar toGregorianCalendar();

     /**

------------------------------------------------------------------------

@@ -1047,13 +1061,13 @@
      * @return TimeZone for this.
      */
     public abstract TimeZone getTimeZone(int defaultZoneoffset);


-
     /**
      * Creates and returns a copy of this object.
      *
      * @return copy of this {@code Object}
      */
+ @Override
    public abstract Object clone();
 }


Thanks,
Joe


On 7/19/2016 6:26 AM, Svetlana Nikandrova wrote:

Hi Joe,
thank you for your replay. As I'm new to javadoc writing feel free to add any comments. 
Please see updated webrev:
http://cr.openjdk.java.net/~snikandrova/8021787/webrev.01/ <http://cr.openjdk.java.net/%7Esnikandrova/8021787/webrev.01/> 

Thank you,
Svetlana

On 18.07.2016 20:34, huizhe wang wrote:

Hi Svetlana,
Thanks for working on these bugs. The change is correct. It would be better to say: "Returns the month of this calendar", in both the returns tag and the description (not number of month).
While we are in this class, it would be good to at least fix the missing @returns tags in a number of methods, e.g. getDay, getTimezone, getHour, getMinute, toGregorianCalendar. Also, it @Override equals, hashCode, toString, and clone. 

Thanks,

Joe

On 7/18/2016 8:49 AM, Svetlana Nikandrova wrote:

Hello all,
please review this javadoc fix for javax.xml.datatype.XMLGregorianCalendar.getMonth() 
Webrev:
http://cr.openjdk.java.net/~snikandrova/8021787/webrev.00/ <http://cr.openjdk.java.net/%7Esnikandrova/8021787/webrev.00/> 
JBS:
https://bugs.openjdk.java.net/browse/JDK-8021787

Thank you,
Svetlana

Reply via email to