RFR (JAXP): 8021787: javax.xml.datatype.XMLGregorianCalendar.getMonth() return is documented wrong
huizhe wang
huizhe.wang at oracle.com
Thu Jul 21 16:25:13 UTC 2016
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
>>
>
More information about the core-libs-dev
mailing list