Summary

Update the javadoc of the Calendar.DAY_OF_WEEK field to clarify the acceptable values depending on leniency of the calendar.

Problem

The current phrasing of Calendar.DAY_OF_WEEK reads that the field only accepts one of Calendar.SUNDAY ... Calendar.SATURDAY. However, if the calendar is non-lenient, the field accepts any int value.

Solution

Clarify the doc of Calendar.DAY_OF_WEEK that the field takes in any int value if the calendar is lenient.

Specification

--- a/src/java.base/share/classes/java/util/Calendar.java
+++ b/src/java.base/share/classes/java/util/Calendar.java
@@ -459,9 +459,11 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca

     /**
      * Field number for {@code get} and {@code set} indicating the day
-     * of the week.  This field takes values {@code SUNDAY},
-     * {@code MONDAY}, {@code TUESDAY}, {@code WEDNESDAY},
-     * {@code THURSDAY}, {@code FRIDAY}, and {@code SATURDAY}.
+     * of the week. If the calendar is non-lenient, this field takes values
+     * {@code SUNDAY}, {@code MONDAY}, {@code TUESDAY}, {@code WEDNESDAY},
+     * {@code THURSDAY}, {@code FRIDAY}, and {@code SATURDAY}. Otherwise, any
+     * int values are accepted and normalized to one of the previously
+     * mentioned values.
      *
      * @see #SUNDAY
      * @see #MONDAY