RFR (JAXP): 8021787: javax.xml.datatype.XMLGregorianCalendar.getMonth() return is documented wrong
huizhe wang
huizhe.wang at oracle.com
Mon Jul 25 17:48:33 UTC 2016
Thanks Svetlana. The patch looks good to me.
-Joe
On 7/25/2016 5:42 AM, Svetlana Nikandrova wrote:
> Hi Joe, Roger,
>
> thank you for your replays. A have changed javadoc as Joe suggested
> (hope I didn't missed any in-line comments) and added a bunch of "s"
> and "The" to Returns and @return.
> Hope now it looks better and more consistent:
> http://cr.openjdk.java.net/~snikandrova/8021787/webrev.02/
> <http://cr.openjdk.java.net/%7Esnikandrova/8021787/webrev.02/>
>
> Thank you,
> Svetlana
>
> On 21.07.2016 19:32, huizhe wang wrote:
>> 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
>>>>>
>>>>
>>>
>>
>
More information about the core-libs-dev
mailing list