RFR (JAXP): 8021787: javax.xml.datatype.XMLGregorianCalendar.getMonth() return is documented wrong
Svetlana Nikandrova
svetlana.nikandrova at oracle.com
Mon Jul 25 12:42:49 UTC 2016
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