RFR (JAXP): 8021787: javax.xml.datatype.XMLGregorianCalendar.getMonth() return is documented wrong
huizhe wang
huizhe.wang at oracle.com
Thu Jul 21 16:32:33 UTC 2016
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