Summary

Add an example to Calendar.add() especially for the leap day behavior

Problem

Users may be confused about the behavior of subtracting a year and then adding a year to a leap day of GregorianCalendar, which won't guarantee a round trip.

Solution

Add an example to the existing Example paragraph for the add() method in the java.util.Calendar class description.

Specification

Modify the java.util.Calendar class description as:

--- a/src/java.base/share/classes/java/util/Calendar.java
+++ b/src/java.base/share/classes/java/util/Calendar.java
@@ -282,7 +282,9 @@
  * {@code DAY_OF_MONTH} to 30, the closest possible value. Although
  * it is a smaller field, {@code DAY_OF_WEEK} is not adjusted by
  * rule 2, since it is expected to change when the month changes in a
- * {@code GregorianCalendar}.</p>
+ * {@code GregorianCalendar}. In leap years, the adjustment accounts
+ * for the leap day in February to ensure the day of month is valid
+ * for the year.</p>
  *
  * <p><strong>{@code roll(f, delta)}</strong> adds
  * {@code delta} to field {@code f} without changing larger