Summary

DateFormat.Field::getCalendarField() claims that it will return -1 if there is no associated Calendar constant, which is not always true.

Problem

A DateFormat.Field is created via the Field(String name, int calendarField) constructor. The built in DateFormat.Field(s) are all created with calendarField equal to -1, if there is no Calendar constant. However, a user can subclass and create their own DateFormat.Field via the protected constructor with calendarField equal to anything, even if there is no Calendar constant. This is because the constructor does not actually make any checks on the value, although it is recommended in the specification to use -1. Thus, the method getCalendarField which simply returns the private member variable calendarField will not always return -1 if there is no associated Calendar constant.

Solution

Clarify that the default implementation always returns -1 if there is no Calendar constant using an implSpec tag. Change the existing wording from stating that it always returns -1 if there is no Calendar constant to returning -1 guarantees there is no Calendar constant.

Specification

Update DateFormat.Field::getCalendarField()

         /**
          * Returns the {@code Calendar} field associated with this
          * attribute. For example, if this represents the hours field of
-         * a {@code Calendar}, this would return
-         * {@code Calendar.HOUR}. If there is no corresponding
-         * {@code Calendar} constant, this will return -1.
+         * a {@code Calendar}, this method would return {@code Calendar.HOUR}.
+         * The return value of {@code -1} guarantees that this field does not
+         * represent any corresponding constant in {@code Calendar}.
+         *
+         * @implSpec The default implementation always returns {@code -1} if it does
+         * not represent any corresponding constant in {@code Calendar}.