[Doc] Wrong Months Array for DateFormatSymbols

Summary

Clarify the API Doc of DateFormatSymbols.getMonths/getShortMonths to describe the 13th element returned in the months array.

Problem

DateFormatSymbols class was designed considering future support for Lunisolar Calendar Systems, such as Chinese which have 13th Month such as Calendar.UNDECIMBER. For other calendar systems, this 13th month name will be an empty string. Thus, methods getMonths() and getShortMonths() return an empty string as 13th element for other calendar systems. However, this is perceived as a bug from end user.

Solution

Solution is to clarify API Doc of DateFormatSymbols's methods getMonths() and getShortMonths().

Specification

Here is the proposed spec change :

changing specification of java.text.DateFormatSymbols.getMonths()

from:

 /**
  * Gets month strings. For example: "January", "February", etc.
  *
  * <p>If the language requires different forms for formatting and
  * stand-alone usages, this method returns month names in the
  * Calendar Elements in the Unicode Locale Data Markup Language
  * (LDML) specification</a> for more details.
  *
  * @return the month strings. Use
  * {@link java.util.Calendar#JANUARY Calendar.JANUARY},
  * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
  * etc. to index the result array. 
  */

to

           /**
           * Gets month strings. For example: "January", "February", etc.
+         * An array with either 12 or 13 elements will be returned depending
+         * on whether or not {@link java.util.Calendar#UNDECIMBER Calendar.UNDECIMBER}
+         * is supported. Use
+         * {@link java.util.Calendar#JANUARY Calendar.JANUARY},
+         * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
+         * etc. to index the result array.
          *
          * <p>If the language requires different forms for formatting and
          * stand-alone usages, this method returns month names in the
          * Calendar Elements in the Unicode Locale Data Markup Language
          * (LDML) specification</a> for more details.
          *
          * @return the month strings.
-         * Use {@link java.util.Calendar#JANUARY Calendar.JANUARY},
-         * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
-         * etc. to index the result array.
+         * @implSpec This method returns 13 elements since 
+         * {@link java.util.Calendar#UNDECIMBER Calendar.UNDECIMBER} is supported.
+         * @return the month strings. 
           */

Changing specification of java.text.DateFormatSymbols.getShortMonths() from

from:

 /**
  * Gets short month strings. For example: "January", "February", etc.
  *
  * <p>If the language requires different forms for formatting and
  * stand-alone usages, this method returns short month names in the
  * Calendar Elements in the Unicode Locale Data Markup Language
  * (LDML) specification</a> for more details.
  *
  * @return the short month strings. Use
  * {@link java.util.Calendar#JANUARY Calendar.JANUARY},
  * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
  * etc. to index the result array. 
  */

to

           /**
           * Gets short month strings. For example: "January", "February", etc.
+         * An array with either 12 or 13 elements will be returned depending
+         * on whether or not {@link java.util.Calendar#UNDECIMBER Calendar.UNDECIMBER}
+         * is supported. Use
+         * {@link java.util.Calendar#JANUARY Calendar.JANUARY},
+         * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
+         * etc. to index the result array.
          *
          * <p>If the language requires different forms for formatting and
          * stand-alone usages, this method returns short month names in the
          * Calendar Elements in the Unicode Locale Data Markup Language
          * (LDML) specification</a> for more details.
          *
          * @return the short month strings.
-         * Use  {@link java.util.Calendar#JANUARY Calendar.JANUARY},
-         * {@link java.util.Calendar#FEBRUARY Calendar.FEBRUARY},
-         * etc. to index the result array.
+         * @implSpec This method returns 13 elements since 
+         * {@link java.util.Calendar#UNDECIMBER Calendar.UNDECIMBER} is supported.
+         * @return the month strings. 
           */