4737887: (cal) API: Calendar methods taking field should document exceptions

Reviewed-by: naoto
This commit is contained in:
Justin Lu 2023-04-20 21:11:00 +00:00 committed by Naoto Sato
parent f63362310e
commit 174c1a6d53

@ -105,6 +105,10 @@ import sun.util.spi.CalendarProvider;
* the Epoch) or values of the calendar fields. Calling the
* {@code get}, {@code getTimeInMillis}, {@code getTime},
* {@code add} and {@code roll} involves such calculation.
* Unless otherwise specified, any {@code Calendar} method containing the
* parameter {@code int field} will throw an {@code ArrayIndexOutOfBoundsException}
* if the specified field is out of range ({@code field} < 0 ||
* {@code field} >= {@link #FIELD_COUNT}).
*
* <h3>Leniency</h3>
*
@ -1844,8 +1848,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
*
* @param field the given calendar field.
* @return the value for the given calendar field.
* @throws ArrayIndexOutOfBoundsException if the specified field is out of range
* (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
* @throws IllegalArgumentException if this {@code Calendar} is non-lenient and any
* of the calendar fields have invalid values.
* @see #set(int,int)
* @see #complete()
*/
@ -1873,8 +1877,6 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
* not affect any setting state of the field in this
* {@code Calendar} instance.
*
* @throws IndexOutOfBoundsException if the specified field is out of range
* (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
* @see #areFieldsSet
* @see #isTimeSet
* @see #areAllFieldsSet
@ -1891,9 +1893,6 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
*
* @param field the given calendar field.
* @param value the value to be set for the given calendar field.
* @throws ArrayIndexOutOfBoundsException if the specified field is out of range
* (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
* in non-lenient mode.
* @see #set(int,int,int)
* @see #set(int,int,int,int,int)
* @see #set(int,int,int,int,int,int)
@ -2816,6 +2815,9 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
*
* @param field the calendar field.
* @param amount the amount of date or time to be added to the field.
* @throws IllegalArgumentException if this {@code Calendar} is non-lenient
* and any of the calendar fields have invalid values or if {@code field} is
* {@code ZONE_OFFSET}, {@code DST_OFFSET}, or unknown.
* @see #roll(int,int)
* @see #set(int,int)
*/
@ -2838,6 +2840,9 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
* @param field the time field.
* @param up indicates if the value of the specified time field is to be
* rolled up or rolled down. Use true if rolling up, false otherwise.
* @throws IllegalArgumentException if this {@code Calendar} is non-lenient
* and any of the calendar fields have invalid values or if {@code field} is
* {@code ZONE_OFFSET}, {@code DST_OFFSET}, or unknown.
* @see Calendar#add(int,int)
* @see Calendar#set(int,int)
*/
@ -2857,6 +2862,9 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
*
* @param field the calendar field.
* @param amount the signed amount to add to the calendar {@code field}.
* @throws IllegalArgumentException if this {@code Calendar} is non-lenient
* and any of the calendar fields have invalid values or if {@code field} is
* {@code ZONE_OFFSET}, {@code DST_OFFSET}, or unknown.
* @since 1.2
* @see #roll(int,boolean)
* @see #add(int,int)