Name: boT120536 Date: 12/20/2000


this bug is about documentation


  Bug 4349844

METHOD documentation for Calendar.roll and GregorianCalendar.roll
does not explain what "roll" means, and does not make clear that
there is a distinction between roll and add.

http://java.sun.com/j2se/1.3/docs/api/java/util/Calendar.html#roll(int, boolean)
http://java.sun.com/j2se/1.3/docs/api/java/util/GregorianCalendar.html#roll(int,
boolean)

While the Calendar CLASS documentation includes information cited in
the bug evaluation, the roll METHOD documentation does not, and the
GregorianCalendar documentation does not. People tend to look for a
method until they find one that sounds right, and unfortunately some
find the "roll" method and don't find the "add" method and never see
the Calendar class documentation, particularly since most are using
GregorianCalendar. I suggest that the
Calendar.roll and GregorianCalendar.roll METHOD documentation
be updated to say

roll(f, delta) adds delta to field f without changing larger f

and cross reference the Calendar CLASS documentation for further examples.
(Review ID: 111645)
======================================================================