harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772785 [10/12] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/
Date Thu, 07 May 2009 21:43:44 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SimpleTimeZone.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SimpleTimeZone.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SimpleTimeZone.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SimpleTimeZone.java Thu May  7 21:43:41 2009
@@ -27,10 +27,17 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * SimpleTimeZone represents a local time zone and its daylight savings time
- * rules for the gregorian calendar.
- * 
+ * {@code SimpleTimeZone} is a concrete subclass of {@code TimeZone}
+ * that represents a time zone for use with a Gregorian calendar. This class
+ * does not handle historical changes.
+ * <p>
+ * Use a negative value for {@code dayOfWeekInMonth} to indicate that
+ * {@code SimpleTimeZone} should count from the end of the month
+ * backwards. For example, Daylight Savings Time ends at the last
+ * (dayOfWeekInMonth = -1) Sunday in October, at 2 AM in standard time.
+ *
  * @see Calendar
+ * @see GregorianCalendar
  * @see TimeZone
  */
 public class SimpleTimeZone extends TimeZone {
@@ -56,19 +63,21 @@
     private static final int DOM_MODE = 1, DOW_IN_MONTH_MODE = 2,
             DOW_GE_DOM_MODE = 3, DOW_LE_DOM_MODE = 4;
 
-    /* Constant for representing start or end time in GMT time mode. */
+    /**
+     * The constant for representing a start or end time in GMT time mode.
+     */
     public static final int UTC_TIME = 2;
 
-    /*
-     * Constant for representing start or end time in standard local time mode,
-     * based on timezone's raw offset from GMT, does not include Daylight
+    /**
+     * The constant for representing a start or end time in standard local time mode,
+     * based on timezone's raw offset from GMT; does not include Daylight
      * savings.
      */
     public static final int STANDARD_TIME = 1;
 
-    /*
-     * Constant for representing start or end time in local wall clock time
-     * mode, based on timezone's adjusted offset from GMT, it does include
+    /**
+     * The constant for representing a start or end time in local wall clock time
+     * mode, based on timezone's adjusted offset from GMT; includes
      * Daylight savings.
      */
     public static final int WALL_TIME = 0;
@@ -84,13 +93,16 @@
     private final transient boolean isSimple;
 
     /**
-     * Constructs a new SimpleTimeZone using the specified offset for standard
-     * time from GMT and the specified time zone ID.
+     * Constructs a {@code SimpleTimeZone} with the given base time zone offset from GMT
+     * and time zone ID. Timezone IDs can be obtained from
+     * {@code TimeZone.getAvailableIDs}. Normally you should use {@code TimeZone.getDefault} to
+     * construct a {@code TimeZone}.
      * 
      * @param offset
-     *            the offset from GMT of standard time in milliseconds
+     *            the given base time zone offset to GMT.
      * @param name
-     *            the time zone ID
+     *            the time zone ID which is obtained from
+     *            {@code TimeZone.getAvailableIDs}.
      */
     public SimpleTimeZone(int offset, final String name) {
         setID(name);
@@ -106,36 +118,73 @@
     }
 
     /**
-     * Constructs a new SimpleTimeZone using the specified offset for standard
-     * time from GMT, the specified time zone ID and the rules for daylight
-     * savings time.
-     * 
+     * Constructs a {@code SimpleTimeZone} with the given base time zone offset from GMT,
+     * time zone ID, and times to start and end the daylight savings time. Timezone IDs can
+     * be obtained from {@code TimeZone.getAvailableIDs}. Normally you should use
+     * {@code TimeZone.getDefault} to create a {@code TimeZone}. For a time zone that does not
+     * use daylight saving time, do not use this constructor; instead you should
+     * use {@code SimpleTimeZone(rawOffset, ID)}.
+     * <p>
+     * By default, this constructor specifies day-of-week-in-month rules. That
+     * is, if the {@code startDay} is 1, and the {@code startDayOfWeek} is {@code SUNDAY}, then this
+     * indicates the first Sunday in the {@code startMonth}. A {@code startDay} of -1 likewise
+     * indicates the last Sunday. However, by using negative or zero values for
+     * certain parameters, other types of rules can be specified.
+     * <p>
+     * Day of month: To specify an exact day of the month, such as March 1, set
+     * {@code startDayOfWeek} to zero.
+     * <p>
+     * Day of week after day of month: To specify the first day of the week
+     * occurring on or after an exact day of the month, make the day of the week
+     * negative. For example, if {@code startDay} is 5 and {@code startDayOfWeek} is {@code -MONDAY},
+     * this indicates the first Monday on or after the 5th day of the
+     * {@code startMonth}.
+     * <p>
+     * Day of week before day of month: To specify the last day of the week
+     * occurring on or before an exact day of the month, make the day of the
+     * week and the day of the month negative. For example, if {@code startDay} is {@code -21}
+     * and {@code startDayOfWeek} is {@code -WEDNESDAY}, this indicates the last Wednesday on or
+     * before the 21st of the {@code startMonth}.
+     * <p>
+     * The above examples refer to the {@code startMonth}, {@code startDay}, and {@code startDayOfWeek};
+     * the same applies for the {@code endMonth}, {@code endDay}, and {@code endDayOfWeek}.
+     * <p>
+     * The daylight savings time difference is set to the default value: one hour.
+     *
      * @param offset
-     *            the offset from GMT of standard time in milliseconds
+     *            the given base time zone offset to GMT.
      * @param name
-     *            the time zone ID
+     *            the time zone ID which is obtained from
+     *            {@code TimeZone.getAvailableIDs}.
      * @param startMonth
-     *            the Calendar month in which daylight savings time starts
+     *            the daylight savings starting month. The month indexing is 0-based. eg, 0
+     *            for January.
      * @param startDay
-     *            the occurrence of the day of the week on which daylight
-     *            savings time starts
+     *            the daylight savings starting day-of-week-in-month. Please see
+     *            the member description for an example.
      * @param startDayOfWeek
-     *            the Calendar day of the week on which daylight savings time
-     *            starts
+     *            the daylight savings starting day-of-week. Please see the
+     *            member description for an example.
      * @param startTime
-     *            the time of day in milliseconds on which daylight savings time
-     *            starts
+     *            the daylight savings starting time in local wall time, which
+     *            is standard time in this case. Please see the member
+     *            description for an example.
      * @param endMonth
-     *            the Calendar month in which daylight savings time ends
+     *            the daylight savings ending month. The month indexing is 0-based. eg, 0 for
+     *            January.
      * @param endDay
-     *            the occurrence of the day of the week on which daylight
-     *            savings time ends
+     *            the daylight savings ending day-of-week-in-month. Please see
+     *            the member description for an example.
      * @param endDayOfWeek
-     *            the Calendar day of the week on which daylight savings time
-     *            ends
+     *            the daylight savings ending day-of-week. Please see the member
+     *            description for an example.
      * @param endTime
-     *            the time of day in milliseconds standard time on which
-     *            daylight savings time ends
+     *            the daylight savings ending time in local wall time, which is
+     *            daylight time in this case. Please see the member description
+     *            for an example.
+     * @throws IllegalArgumentException
+     *             if the month, day, dayOfWeek, or time parameters are out of
+     *             range for the start or end rule.
      */
     public SimpleTimeZone(int offset, String name, int startMonth,
             int startDay, int startDayOfWeek, int startTime, int endMonth,
@@ -145,38 +194,46 @@
     }
 
     /**
-     * Constructs a new SimpleTimeZone using the specified offset for standard
-     * time from GMT, the specified time zone ID and the rules for daylight
-     * savings time.
-     * 
+     * Constructs a {@code SimpleTimeZone} with the given base time zone offset from GMT,
+     * time zone ID, times to start and end the daylight savings time, and
+     * the daylight savings time difference in milliseconds.
+     *
      * @param offset
-     *            the offset from GMT of standard time in milliseconds
+     *            the given base time zone offset to GMT.
      * @param name
-     *            the time zone ID
+     *            the time zone ID which is obtained from
+     *            {@code TimeZone.getAvailableIDs}.
      * @param startMonth
-     *            the Calendar month in which daylight savings time starts
+     *            the daylight savings starting month. Month is 0-based. eg, 0
+     *            for January.
      * @param startDay
-     *            the occurrence of the day of the week on which daylight
-     *            savings time starts
+     *            the daylight savings starting day-of-week-in-month. Please see
+     *            the description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
      * @param startDayOfWeek
-     *            the Calendar day of the week on which daylight savings time
-     *            starts
+     *            the daylight savings starting day-of-week. Please see the
+     *            description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
      * @param startTime
-     *            the time of day in milliseconds on which daylight savings time
-     *            starts
+     *            The daylight savings starting time in local wall time, which
+     *            is standard time in this case. Please see the description of
+     *            {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
      * @param endMonth
-     *            the Calendar month in which daylight savings time ends
+     *            the daylight savings ending month. Month is 0-based. eg, 0 for
+     *            January.
      * @param endDay
-     *            the occurrence of the day of the week on which daylight
-     *            savings time ends
+     *            the daylight savings ending day-of-week-in-month. Please see
+     *            the description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
      * @param endDayOfWeek
-     *            the Calendar day of the week on which daylight savings time
-     *            ends
+     *            the daylight savings ending day-of-week. Please see the description of
+     *            {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
      * @param endTime
-     *            the time of day in milliseconds standard time on which
-     *            daylight savings time ends
+     *            the daylight savings ending time in local wall time, which is
+     *            daylight time in this case. Please see the description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)}
+     *            for an example.
      * @param daylightSavings
-     *            the daylight savings time difference in milliseconds
+     *            the daylight savings time difference in milliseconds.
+     * @throws IllegalArgumentException
+     *                if the month, day, dayOfWeek, or time parameters are out of
+     *                range for the start or end rule.
      */
     public SimpleTimeZone(int offset, String name, int startMonth,
             int startDay, int startDayOfWeek, int startTime, int endMonth,
@@ -207,42 +264,50 @@
     }
 
     /**
-     * Constructs a new SimpleTimeZone using the specified offset for standard
-     * time from GMT, the specified time zone ID, the rules for daylight savings
-     * time, and the modes indicating UTC, standard, or wall time.
-     * 
+     * Construct a {@code SimpleTimeZone} with the given base time zone offset from GMT,
+     * time zone ID, times to start and end the daylight savings time including a
+     * mode specifier, the daylight savings time difference in milliseconds.
+     * The mode specifies either {@link #WALL_TIME}, {@link #STANDARD_TIME}, or
+     * {@link #UTC_TIME}.
+     *
      * @param offset
-     *            the offset from GMT of standard time in milliseconds
+     *            the given base time zone offset to GMT.
      * @param name
-     *            the time zone ID
+     *            the time zone ID which is obtained from
+     *            {@code TimeZone.getAvailableIDs}.
      * @param startMonth
-     *            the Calendar month in which daylight savings time starts
+     *            the daylight savings starting month. The month indexing is 0-based. eg, 0
+     *            for January.
      * @param startDay
-     *            the occurrence of the day of the week on which daylight
-     *            savings time starts
+     *            the daylight savings starting day-of-week-in-month. Please see
+     *            the description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
      * @param startDayOfWeek
-     *            the Calendar day of the week on which daylight savings time
-     *            starts
+     *            the daylight savings starting day-of-week. Please see the
+     *            description of {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
      * @param startTime
-     *            the time of day in milliseconds on which daylight savings time
-     *            starts
+     *            the time of day in milliseconds on which daylight savings
+     *            time starts, based on the {@code startTimeMode}.
      * @param startTimeMode
-     *            the mode (UTC, standard, or wall time) of the start time value
-     * @param endMonth
-     *            the Calendar month in which daylight savings time ends
+     *            the mode (UTC, standard, or wall time) of the start time
+     *            value.
      * @param endDay
-     *            the occurrence of the day of the week on which daylight
-     *            savings time ends
+     *            the day of the week on which daylight savings time ends.
+     * @param endMonth
+     *            the daylight savings ending month. The month indexing is 0-based. eg, 0 for
+     *            January.
      * @param endDayOfWeek
-     *            the Calendar day of the week on which daylight savings time
-     *            ends
+     *            the daylight savings ending day-of-week. Please see the description of
+     *            {@link #SimpleTimeZone(int, String, int, int, int, int, int, int, int, int)} for an example.
      * @param endTime
-     *            the time of day in milliseconds standard time on which
-     *            daylight savings time ends
+     *            the time of day in milliseconds on which daylight savings
+     *            time ends, based on the {@code endTimeMode}.
      * @param endTimeMode
-     *            the mode (UTC, standard, or wall time) of the end time value
+     *            the mode (UTC, standard, or wall time) of the end time value.
      * @param daylightSavings
-     *            the daylight savings time difference in milliseconds
+     *            the daylight savings time difference in milliseconds.
+     * @throws IllegalArgumentException
+     *             if the month, day, dayOfWeek, or time parameters are out of
+     *             range for the start or end rule.
      */
     public SimpleTimeZone(int offset, String name, int startMonth,
             int startDay, int startDayOfWeek, int startTime, int startTimeMode,
@@ -256,11 +321,10 @@
     }
 
     /**
-     * Answers a new SimpleTimeZone with the same ID, rawOffset and daylight
+     * Returns a new {@code SimpleTimeZone} with the same ID, {@code rawOffset} and daylight
      * savings time rules as this SimpleTimeZone.
      * 
-     * @return a shallow copy of this SimpleTimeZone
-     * 
+     * @return a shallow copy of this {@code SimpleTimeZone}.
      * @see java.lang.Cloneable
      */
     @Override
@@ -273,15 +337,14 @@
     }
 
     /**
-     * Compares the specified object to this SimpleTimeZone and answer if they
-     * are equal. The object must be an instance of SimpleTimeZone and have the
-     * same properties.
+     * Compares the specified object to this {@code SimpleTimeZone} and returns whether they
+     * are equal. The object must be an instance of {@code SimpleTimeZone} and have the
+     * same internal data.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this SimpleTimeZone,
-     *         false otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this
+     *         {@code SimpleTimeZone}, {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -303,13 +366,6 @@
                         && endTime == tz.endTime && endMode == tz.endMode && dstSavings == tz.dstSavings));
     }
 
-    /**
-     * Gets the daylight savings offset in milliseconds for this SimpleTimeZone.
-     * 
-     * If this SimpleTimezone does not observe daylight savings, returns 0.
-     * 
-     * @return the daylight savings offset in milliseconds
-     */
     @Override
     public int getDSTSavings() {
         if (!useDaylight) {
@@ -318,26 +374,6 @@
         return dstSavings;
     }
 
-    /**
-     * Gets the offset from GMT of this SimpleTimeZone for the specified date
-     * and time. The offset includes daylight savings time if the specified date
-     * and time are within the daylight savings time period.
-     * 
-     * @param era
-     *            the GregorianCalendar era, either GregorianCalendar.BC or
-     *            GregorianCalendar.AD
-     * @param year
-     *            the year
-     * @param month
-     *            the Calendar month
-     * @param day
-     *            the day of the month
-     * @param dayOfWeek
-     *            the Calendar day of the week
-     * @param time
-     *            the time of day in milliseconds
-     * @return the offset from GMT in milliseconds
-     */
     @Override
     public int getOffset(int era, int year, int month, int day, int dayOfWeek,
             int time) {
@@ -351,36 +387,21 @@
         return icuTZ.getOffset(era, year, month, day, dayOfWeek, time);
     }
 
-    /**
-     * Gets the offset from GMT of this SimpleTimeZone for the specified date.
-     * The offset includes daylight savings time if the specified date is within
-     * the daylight savings time period.
-     * 
-     * @param time
-     *            the date in milliseconds since January 1, 1970 00:00:00 GMT
-     * @return the offset from GMT in milliseconds
-     */
     @Override
     public int getOffset(long time) {
         return icuTZ.getOffset(time);
     }
 
-    /**
-     * Gets the offset for standard time from GMT for this SimpleTimeZone.
-     * 
-     * @return the offset from GMT of standard time in milliseconds
-     */
     @Override
     public int getRawOffset() {
         return rawOffset;
     }
 
     /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
-     * 
-     * @return the receiver's hash
+     * Returns an integer hash code for the receiver. Objects which are equal
+     * return the same value for this method.
      * 
+     * @return the receiver's hash.
      * @see #equals
      */
     @Override
@@ -394,15 +415,6 @@
         return hashCode;
     }
 
-    /**
-     * Answers if the specified TimeZone has the same raw offset and daylight
-     * savings time rules as this SimpleTimeZone.
-     * 
-     * @param zone
-     *            a TimeZone
-     * @return true when the TimeZones have the same raw offset and daylight
-     *         savings time rules, false otherwise
-     */
     @Override
     public boolean hasSameRules(TimeZone zone) {
         if (!(zone instanceof SimpleTimeZone)) {
@@ -424,15 +436,6 @@
                 && endTime == tz.endTime && endMode == tz.endMode;
     }
 
-    /**
-     * Answers if the specified Date is in the daylight savings time period for
-     * this SimpleTimeZone.
-     * 
-     * @param time
-     *            a Date
-     * @return true when the Date is in the daylight savings time period, false
-     *         otherwise
-     */
     @Override
     public boolean inDaylightTime(Date time) {
         return icuTZ.inDaylightTime(time);
@@ -446,10 +449,10 @@
     }
 
     /**
-     * Sets the daylight savings offset in milliseconds for this SimpleTimeZone.
+     * Sets the daylight savings offset in milliseconds for this {@code SimpleTimeZone}.
      * 
      * @param milliseconds
-     *            the daylight savings offset in milliseconds
+     *            the daylight savings offset in milliseconds.
      */
     public void setDSTSavings(int milliseconds) {
         if (milliseconds > 0) {
@@ -514,13 +517,13 @@
      * Sets the rule which specifies the end of daylight savings time.
      * 
      * @param month
-     *            the Calendar month in which daylight savings time ends
+     *            the {@code Calendar} month in which daylight savings time ends.
      * @param dayOfMonth
-     *            the Calendar day of the month on which daylight savings time
-     *            ends
+     *            the {@code Calendar} day of the month on which daylight savings time
+     *            ends.
      * @param time
      *            the time of day in milliseconds standard time on which
-     *            daylight savings time ends
+     *            daylight savings time ends.
      */
     public void setEndRule(int month, int dayOfMonth, int time) {
         endMonth = month;
@@ -538,16 +541,16 @@
      * Sets the rule which specifies the end of daylight savings time.
      * 
      * @param month
-     *            the Calendar month in which daylight savings time ends
+     *            the {@code Calendar} month in which daylight savings time ends.
      * @param day
      *            the occurrence of the day of the week on which daylight
-     *            savings time ends
+     *            savings time ends.
      * @param dayOfWeek
-     *            the Calendar day of the week on which daylight savings time
-     *            ends
+     *            the {@code Calendar} day of the week on which daylight savings time
+     *            ends.
      * @param time
      *            the time of day in milliseconds standard time on which
-     *            daylight savings time ends
+     *            daylight savings time ends.
      */
     public void setEndRule(int month, int day, int dayOfWeek, int time) {
         endMonth = month;
@@ -565,17 +568,17 @@
      * Sets the rule which specifies the end of daylight savings time.
      * 
      * @param month
-     *            the Calendar month in which daylight savings time ends
+     *            the {@code Calendar} month in which daylight savings time ends.
      * @param day
-     *            the Calendar day of the month
+     *            the {@code Calendar} day of the month.
      * @param dayOfWeek
-     *            the Calendar day of the week on which daylight savings time
-     *            ends
+     *            the {@code Calendar} day of the week on which daylight savings time
+     *            ends.
      * @param time
      *            the time of day in milliseconds on which daylight savings time
-     *            ends
+     *            ends.
      * @param after
-     *            selects the day after or before the day of month
+     *            selects the day after or before the day of month.
      */
     public void setEndRule(int month, int day, int dayOfWeek, int time,
             boolean after) {
@@ -591,10 +594,10 @@
     }
 
     /**
-     * Sets the offset for standard time from GMT for this SimpleTimeZone.
+     * Sets the offset for standard time from GMT for this {@code SimpleTimeZone}.
      * 
      * @param offset
-     *            the offset from GMT of standard time in milliseconds
+     *            the offset from GMT of standard time in milliseconds.
      */
     @Override
     public void setRawOffset(int offset) {
@@ -638,13 +641,13 @@
      * Sets the rule which specifies the start of daylight savings time.
      * 
      * @param month
-     *            the Calendar month in which daylight savings time starts
+     *            the {@code Calendar} month in which daylight savings time starts.
      * @param dayOfMonth
-     *            the Calendar day of the month on which daylight savings time
-     *            starts
+     *            the {@code Calendar} day of the month on which daylight savings time
+     *            starts.
      * @param time
      *            the time of day in milliseconds on which daylight savings time
-     *            starts
+     *            starts.
      */
     public void setStartRule(int month, int dayOfMonth, int time) {
         startMonth = month;
@@ -662,16 +665,16 @@
      * Sets the rule which specifies the start of daylight savings time.
      * 
      * @param month
-     *            the Calendar month in which daylight savings time starts
+     *            the {@code Calendar} month in which daylight savings time starts.
      * @param day
      *            the occurrence of the day of the week on which daylight
-     *            savings time starts
+     *            savings time starts.
      * @param dayOfWeek
-     *            the Calendar day of the week on which daylight savings time
-     *            starts
+     *            the {@code Calendar} day of the week on which daylight savings time
+     *            starts.
      * @param time
      *            the time of day in milliseconds on which daylight savings time
-     *            starts
+     *            starts.
      */
     public void setStartRule(int month, int day, int dayOfWeek, int time) {
         startMonth = month;
@@ -689,17 +692,17 @@
      * Sets the rule which specifies the start of daylight savings time.
      * 
      * @param month
-     *            the Calendar month in which daylight savings time starts
+     *            the {@code Calendar} month in which daylight savings time starts.
      * @param day
-     *            the Calendar day of the month
+     *            the {@code Calendar} day of the month.
      * @param dayOfWeek
-     *            the Calendar day of the week on which daylight savings time
-     *            starts
+     *            the {@code Calendar} day of the week on which daylight savings time
+     *            starts.
      * @param time
      *            the time of day in milliseconds on which daylight savings time
-     *            starts
+     *            starts.
      * @param after
-     *            selects the day after or before the day of month
+     *            selects the day after or before the day of month.
      */
     public void setStartRule(int month, int day, int dayOfWeek, int time,
             boolean after) {
@@ -715,11 +718,11 @@
     }
 
     /**
-     * Sets the starting year for daylight savings time in this SimpleTimeZone.
+     * Sets the starting year for daylight savings time in this {@code SimpleTimeZone}.
      * Years before this start year will always be in standard time.
      * 
      * @param year
-     *            the starting year
+     *            the starting year.
      */
     public void setStartYear(int year) {
         startYear = year;
@@ -727,9 +730,9 @@
     }
 
     /**
-     * Answers the string representation of this SimpleTimeZone.
+     * Returns the string representation of this {@code SimpleTimeZone}.
      * 
-     * @return the string representation of this SimpleTimeZone
+     * @return the string representation of this {@code SimpleTimeZone}.
      */
     @Override
     public String toString() {
@@ -759,12 +762,6 @@
                 + ",endTime=" + endTime + "]"; //$NON-NLS-1$//$NON-NLS-2$
     }
 
-    /**
-     * Answers if this TimeZone has a daylight savings time period.
-     * 
-     * @return true if this time zone has a daylight savings time period, false
-     *         otherwise
-     */
     @Override
     public boolean useDaylightTime() {
         return useDaylight;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedMap.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedMap.java Thu May  7 21:43:41 2009
@@ -17,99 +17,109 @@
 
 package java.util;
 
+
 /**
- * SortedMap is a Map where the iterators sequence in order of the sorted keys.
+ * A map that has its keys ordered. The sorting is according to either the
+ * natural ordering of its keys or the ordering given by a specified comparator.
  */
-public interface SortedMap<K, V> extends Map<K, V> {
-
+public interface SortedMap<K,V> extends Map<K,V> {
+    
     /**
-     * Answers the Comparator used to compare elements in this SortedMap.
+     * Returns the comparator used to compare keys in this sorted map.
      * 
-     * @return a Comparator or null if the natural order is used
+     * @return the comparator or {@code null} if the natural order is used.
      */
     public Comparator<? super K> comparator();
 
     /**
-     * Answer the first sorted key in this SortedMap.
+     * Returns the first key in this sorted map.
      * 
-     * @return the first sorted key
-     * 
-     * @exception NoSuchElementException
-     *                when this SortedMap is empty
+     * @return the first key in this sorted map.
+     * @throws NoSuchElementException
+     *                if this sorted map is empty.
      */
     public K firstKey();
 
     /**
-     * Answers a <code>SortedMap</code> of the specified portion of this
-     * <code>SortedMap</code> which contains keys less than the end key. Users
-     * should be aware that the return value is actually backed by this
-     * <code>SortedMap</code>. Hence any modifications made to one will be
-     * immediately visible to the other.
-     * 
+     * Returns a sorted map over a range of this sorted map with all keys that
+     * are less than the specified {@code endKey}. Changes to the returned
+     * sorted map are reflected in this sorted map and vice versa.
+     * <p>
+     * Note: The returned map will not allow an insertion of a key outside the
+     * specified range.
+     *
      * @param endKey
-     *            the end key
-     * @return a submap where the keys are less than <code>endKey</code>
-     * 
-     * @exception ClassCastException
-     *                when the class of the end key is inappropriate for this
-     *                SubMap
-     * @exception NullPointerException
-     *                when the end key is null and this SortedMap does not
-     *                support null keys
-     */
-    public SortedMap<K, V> headMap(K endKey);
-
-    /**
-     * Answers the last sorted key in this SortedMap.
-     * 
-     * @return the last sorted key
-     * 
-     * @exception NoSuchElementException
-     *                when this SortedMap is empty
+     *            the high boundary of the range specified.
+     * @return a sorted map where the keys are less than {@code endKey}.
+     * @throws ClassCastException
+     *             if the class of the end key is inappropriate for this sorted
+     *             map.
+     * @throws NullPointerException
+     *             if the end key is {@code null} and this sorted map does not
+     *             support {@code null} keys.
+     * @throws IllegalArgumentException
+     *             if this map is itself a sorted map over a range of another
+     *             map and the specified key is outside of its range.
+     */
+    public SortedMap<K,V> headMap(K endKey);
+
+    /**
+     * Returns the last key in this sorted map.
+     * 
+     * @return the last key in this sorted map.
+     * @throws NoSuchElementException
+     *                if this sorted map is empty.
      */
     public K lastKey();
 
     /**
-     * Answers a SortedMap of the specified portion of this SortedMap which
-     * contains keys greater or equal to the start key but less than the end
-     * key. Users should be aware that the return value is actually backed by
-     * this <code>SortedMap</code>. Hence any modifications made to one will
-     * be immediately visible to the other.
-     * 
+     * Returns a sorted map over a range of this sorted map with all keys
+     * greater than or equal to the specified {@code startKey} and less than the
+     * specified {@code endKey}. Changes to the returned sorted map are
+     * reflected in this sorted map and vice versa.
+     * <p>
+     * Note: The returned map will not allow an insertion of a key outside the
+     * specified range.
+     *
      * @param startKey
-     *            the start key
+     *            the low boundary of the range (inclusive).
      * @param endKey
-     *            the end key
-     * @return a submap where the keys are greater or equal to
-     *         <code>startKey</code> and less than <code>endKey</code>
-     * 
-     * @exception ClassCastException
-     *                when the class of the start or end key is inappropriate
-     *                for this SubMap
-     * @exception NullPointerException
-     *                when the start or end key is null and this SortedMap does
-     *                not support null keys
-     * @exception IllegalArgumentException
-     *                when the start key is greater than the end key
-     */
-    public SortedMap<K, V> subMap(K startKey, K endKey);
-
-    /**
-     * Answers a SortedMap of the specified portion of this SortedMap which
-     * contains keys greater or equal to the start key. The returned SortedMap
-     * is backed by this SortedMap so changes to one are reflected by the other.
+     *            the high boundary of the range (exclusive),
+     * @return a sorted map with the key from the specified range.
+     * @throws ClassCastException
+     *             if the class of the start or end key is inappropriate for
+     *             this sorted map.
+     * @throws NullPointerException
+     *             if the start or end key is {@code null} and this sorted map
+     *             does not support {@code null} keys.
+     * @throws IllegalArgumentException
+     *             if the start key is greater than the end key, or if this map
+     *             is itself a sorted map over a range of another sorted map and
+     *             the specified range is outside of its range.
+     */
+    public SortedMap<K,V> subMap(K startKey, K endKey);
+
+    /**
+     * Returns a sorted map over a range of this sorted map with all keys that
+     * are greater than or equal to the specified {@code startKey}. Changes to
+     * the returned sorted map are reflected in this sorted map and vice versa.
+     * <p>
+     * Note: The returned map will not allow an insertion of a key outside the
+     * specified range.
      * 
      * @param startKey
-     *            the start key
-     * @return a submap where the keys are greater or equal to
-     *         <code>startKey</code>
-     * 
-     * @exception ClassCastException
-     *                when the class of the start key is inappropriate for this
-     *                SubMap
-     * @exception NullPointerException
-     *                when the start key is null and this SortedMap does not
-     *                support null keys
+     *            the low boundary of the range specified.
+     * @return a sorted map where the keys are greater or equal to
+     *         {@code startKey}.
+     * @throws ClassCastException
+     *             if the class of the start key is inappropriate for this
+     *             sorted map.
+     * @throws NullPointerException
+     *             if the start key is {@code null} and this sorted map does not
+     *             support {@code null} keys.
+     * @throws IllegalArgumentException
+     *             if this map itself a sorted map over a range of another map
+     *             and the specified key is outside of its range.
      */
-    public SortedMap<K, V> tailMap(K startKey);
+    public SortedMap<K,V> tailMap(K startKey);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedSet.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedSet.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedSet.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/SortedSet.java Thu May  7 21:43:41 2009
@@ -17,97 +17,103 @@
 
 package java.util;
 
+
 /**
- * SortedSet is a Set which iterates its elements in sorted order.
+ * SortedSet is a Set which iterates over its elements in a sorted order. The
+ * order is determined either by the elements natural ordering, or by a
+ * {@link Comparator} which is passed into a concrete implementation at
+ * construction time. All elements in this set must be mutually comparable. The
+ * ordering in this set must be consistent with {@code equals} of its elements.
+ * 
+ * @see Comparator
+ * @see Comparable
  */
 public interface SortedSet<E> extends Set<E> {
-
+    
     /**
-     * Answers the Comparator used to compare elements in this SortedSet.
+     * Returns the comparator used to compare elements in this {@code SortedSet}.
      * 
-     * @return a Comparator or null if the natural order is used
+     * @return a comparator or null if the natural ordering is used.
      */
     public Comparator<? super E> comparator();
 
     /**
-     * Answer the first sorted element in this SortedSet.
-     * 
-     * @return the first sorted element
+     * Returns the first element in this {@code SortedSet}. The first element
+     * is the lowest element.
      * 
-     * @exception NoSuchElementException
-     *                when this SortedSet is empty
+     * @return the first element.
+     * @throws NoSuchElementException
+     *             when this {@code SortedSet} is empty.
      */
     public E first();
 
     /**
-     * Answers a SortedSet of the specified portion of this SortedSet which
-     * contains elements less than the end element. The returned SortedSet is
-     * backed by this SortedSet so changes to one are reflected by the other.
+     * Returns a {@code SortedSet} of the specified portion of this
+     * {@code SortedSet} which contains elements less than the end element. The
+     * returned {@code SortedSet} is backed by this {@code SortedSet} so changes
+     * to one set are reflected by the other.
      * 
      * @param end
-     *            the end element
-     * @return a subset where the elements are less than <code>end</code>
-     * 
-     * @exception ClassCastException
-     *                when the class of the end element is inappropriate for
-     *                this SubSet
-     * @exception NullPointerException
-     *                when the end element is null and this SortedSet does not
-     *                support null elements
+     *            the end element.
+     * @return a subset where the elements are less than {@code end}.
+     * @throws ClassCastException
+     *             when the class of the end element is inappropriate for this
+     *             SubSet.
+     * @throws NullPointerException
+     *             when the end element is null and this {@code SortedSet} does
+     *             not support null elements.
      */
     public SortedSet<E> headSet(E end);
 
     /**
-     * Answer the last sorted element in this SortedSet.
-     * 
-     * @return the last sorted element
+     * Returns the last element in this {@code SortedSet}. The last element is
+     * the highest element.
      * 
-     * @exception NoSuchElementException
-     *                when this SortedSet is empty
+     * @return the last element.
+     * @throws NoSuchElementException
+     *             when this {@code SortedSet} is empty.
      */
     public E last();
 
     /**
-     * Answers a SortedSet of the specified portion of this SortedSet which
-     * contains elements greater or equal to the start element but less than the
-     * end element. The returned SortedSet is backed by this SortedMap so
-     * changes to one are reflected by the other.
+     * Returns a {@code SortedSet} of the specified portion of this
+     * {@code SortedSet} which contains elements greater or equal to the start
+     * element but less than the end element. The returned {@code SortedSet} is
+     * backed by this SortedMap so changes to one set are reflected by the
+     * other.
      * 
      * @param start
-     *            the start element
+     *            the start element.
      * @param end
-     *            the end element
-     * @return a subset where the elements are greater or equal to
-     *         <code>start</code> and less than <code>end</code>
-     * 
-     * @exception ClassCastException
-     *                when the class of the start or end element is
-     *                inappropriate for this SubSet
-     * @exception NullPointerException
-     *                when the start or end element is null and this SortedSet
-     *                does not support null elements
-     * @exception IllegalArgumentException
-     *                when the start element is greater than the end element
+     *            the end element.
+     * @return a subset where the elements are greater or equal to {@code start}
+     *         and less than {@code end}.
+     * @throws ClassCastException
+     *             when the class of the start or end element is inappropriate
+     *             for this SubSet.
+     * @throws NullPointerException
+     *             when the start or end element is null and this
+     *             {@code SortedSet} does not support null elements.
+     * @throws IllegalArgumentException
+     *             when the start element is greater than the end element.
      */
     public SortedSet<E> subSet(E start, E end);
 
     /**
-     * Answers a SortedSet of the specified portion of this SortedSet which
-     * contains elements greater or equal to the start element. The returned
-     * SortedSet is backed by this SortedSet so changes to one are reflected by
-     * the other.
+     * Returns a {@code SortedSet} of the specified portion of this
+     * {@code SortedSet} which contains elements greater or equal to the start
+     * element. The returned {@code SortedSet} is backed by this
+     * {@code SortedSet} so changes to one set are reflected by the other.
      * 
      * @param start
-     *            the start element
-     * @return a subset where the elements are greater or equal to
-     *         <code>start</code>
-     * 
-     * @exception ClassCastException
-     *                when the class of the start element is inappropriate for
-     *                this SubSet
-     * @exception NullPointerException
-     *                when the start element is null and this SortedSet does not
-     *                support null elements
+     *            the start element.
+     * @return a subset where the elements are greater or equal to {@code start} .
+     * @throws ClassCastException
+     *             when the class of the start element is inappropriate for this
+     *             SubSet.
+     * @throws NullPointerException
+     *             when the start element is null and this {@code SortedSet}
+     *             does not support null elements.
      */
     public SortedSet<E> tailSet(E start);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Stack.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Stack.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Stack.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Stack.java Thu May  7 21:43:41 2009
@@ -18,25 +18,25 @@
 package java.util;
 
 /**
- * <code>Stack</code> is a Last-In/First-Out(LIFO) data structure which
- * represents a stack of objects. It enables users to pop and push onto the
- * stack, including null objects. There is no limit to the size of the stack
+ * {@code Stack} is a Last-In/First-Out(LIFO) data structure which represents a
+ * stack of objects. It enables users to pop to and push from the stack,
+ * including null objects. There is no limit to the size of the stack.
  */
 public class Stack<E> extends Vector<E> {
 
     private static final long serialVersionUID = 1224463164541339165L;
 
     /**
-     * Constructs a stack with the default size of <code>Vector</code>.
+     * Constructs a stack with the default size of {@code Vector}.
      */
     public Stack() {
         super();
     }
 
     /**
-     * Determines if the stack is empty or not.
+     * Returns whether the stack is empty or not.
      * 
-     * @return true if the stack is empty, false otherwise
+     * @return {@code true} if the stack is empty, {@code false} otherwise.
      */
     public boolean empty() {
         return elementCount == 0;
@@ -45,9 +45,9 @@
     /**
      * Returns the element at the top of the stack without removing it.
      * 
-     * @return the element at the top of the Stack
-     * @exception EmptyStackException
-     *                when empty() is true
+     * @return the element at the top of the stack.
+     * @throws EmptyStackException
+     *             if the stack is empty.
      * @see #pop
      */
     @SuppressWarnings("unchecked")
@@ -63,8 +63,8 @@
      * Returns the element at the top of the stack and removes it.
      * 
      * @return the element at the top of the stack.
-     * @exception EmptyStackException
-     *                when empty() is true
+     * @throws EmptyStackException
+     *             if the stack is empty.
      * @see #peek
      * @see #push
      */
@@ -81,13 +81,11 @@
     }
 
     /**
-     * Pushes the object from the parameter onto the top of the stack.
+     * Pushes the specified object onto the top of the stack.
      * 
      * @param object
-     *            The object to be added to the stack
-     * 
-     * @return the object argument
-     * 
+     *            The object to be added on top of the stack.
+     * @return the object argument.
      * @see #peek
      * @see #pop
      */
@@ -97,18 +95,20 @@
     }
 
     /**
-     * Returns the index of the first occurrence of the object.
+     * Returns the index of the first occurrence of the object, starting from
+     * the top of the stack.
      * 
-     * @return the index of the first occurrence of the object
-     * @param object
-     *            the object to be searched
+     * @return the index of the first occurrence of the object, assuming that
+     *         the topmost object on the stack has a distance of one.
+     * @param o
+     *            the object to be searched.
      */
-    public synchronized int search(Object object) {
+    public synchronized int search(Object o) {
         final Object[] dumpArray = elementData;
         final int size = elementCount;
-        if (object != null) {
+        if (o != null) {
             for (int i = size - 1; i >= 0; i--) {
-                if (object.equals(dumpArray[i])) {
+                if (o.equals(dumpArray[i])) {
                     return size - i;
                 }
             }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/StringTokenizer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/StringTokenizer.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/StringTokenizer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/StringTokenizer.java Thu May  7 21:43:41 2009
@@ -18,14 +18,88 @@
 package java.util;
 
 /**
- * String tokenizer is used to break a string apart into tokens.
- * 
- * If returnDelimiters is false, successive calls to nextToken() return maximal
- * blocks of characters that do not contain a delimiter.
- * 
- * If returnDelimiters is true, delimiters are considered to be tokens, and
- * successive calls to nextToken() return either a one character delimiter, or a
- * maximal block of text between delimiters.
+ * The {@code StringTokenizer} class allows an application to break a string
+ * into tokens by performing code point comparison. The {@code StringTokenizer}
+ * methods do not distinguish among identifiers, numbers, and quoted strings,
+ * nor do they recognize and skip comments.
+ * <p>
+ * The set of delimiters (the codepoints that separate tokens) may be specified
+ * either at creation time or on a per-token basis.
+ * <p>
+ * An instance of {@code StringTokenizer} behaves in one of three ways,
+ * depending on whether it was created with the {@code returnDelimiters} flag
+ * having the value {@code true} or {@code false}:
+ * <ul>
+ * <li>If returnDelims is {@code false}, delimiter code points serve to separate
+ * tokens. A token is a maximal sequence of consecutive code points that are not
+ * delimiters.
+ * <li>If returnDelims is {@code true}, delimiter code points are themselves
+ * considered to be tokens. In this case a token will be received for each
+ * delimiter code point.
+ * </ul>
+ * <p>
+ * A token is thus either one delimiter code point, or a maximal sequence of
+ * consecutive code points that are not delimiters.
+ * <p>
+ * A {@code StringTokenizer} object internally maintains a current position
+ * within the string to be tokenized. Some operations advance this current
+ * position past the code point processed.
+ * <p>
+ * A token is returned by taking a substring of the string that was used to
+ * create the {@code StringTokenizer} object.
+ * <p>
+ * Here's an example of the use of the default delimiter {@code StringTokenizer}
+ * : <blockquote>
+ *
+ * <pre>
+ * StringTokenizer st = new StringTokenizer(&quot;this is a test&quot;);
+ * while (st.hasMoreTokens()) {
+ *     println(st.nextToken());
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * This prints the following output: <blockquote>
+ *
+ * <pre>
+ *     this
+ *     is
+ *     a
+ *     test
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Here's an example of how to use a {@code StringTokenizer} with a user
+ * specified delimiter: <blockquote>
+ *
+ * <pre>
+ * StringTokenizer st = new StringTokenizer(
+ *         &quot;this is a test with supplementary characters \ud800\ud800\udc00\udc00&quot;,
+ *         &quot; \ud800\udc00&quot;);
+ * while (st.hasMoreTokens()) {
+ *     println(st.nextToken());
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * This prints the following output: <blockquote>
+ *
+ * <pre>
+ *     this
+ *     is
+ *     a
+ *     test
+ *     with
+ *     supplementary
+ *     characters
+ *     \ud800
+ *     \udc00
+ * </pre>
+ *
+ * </blockquote>
  */
 public class StringTokenizer implements Enumeration<Object> {
 
@@ -38,39 +112,46 @@
     private int position;
 
     /**
-     * Constructs a new StringTokenizer for string using whitespace as the
-     * delimiter, returnDelimiters is false.
+     * Constructs a new {@code StringTokenizer} for the parameter string using
+     * whitespace as the delimiter. The {@code returnDelimiters} flag is set to
+     * {@code false}.
      * 
      * @param string
-     *            the string to be tokenized
+     *            the string to be tokenized.
      */
     public StringTokenizer(String string) {
         this(string, " \t\n\r\f", false); //$NON-NLS-1$
     }
 
     /**
-     * Constructs a new StringTokenizer for string using the specified
-     * delimiters, returnDelimiters is false.
+     * Constructs a new {@code StringTokenizer} for the parameter string using
+     * the specified delimiters. The {@code returnDelimiters} flag is set to
+     * {@code false}. If {@code delimiters} is {@code null}, this constructor
+     * doesn't throw an {@code Exception}, but later calls to some methods might
+     * throw a {@code NullPointerException}.
      * 
      * @param string
-     *            the string to be tokenized
+     *            the string to be tokenized.
      * @param delimiters
-     *            the delimiters to use
+     *            the delimiters to use.
      */
     public StringTokenizer(String string, String delimiters) {
         this(string, delimiters, false);
     }
 
     /**
-     * Constructs a new StringTokenizer for string using the specified
-     * delimiters and returning delimiters as tokens when specified.
+     * Constructs a new {@code StringTokenizer} for the parameter string using
+     * the specified delimiters, returning the delimiters as tokens if the
+     * parameter {@code returnDelimiters} is {@code true}. If {@code delimiters}
+     * is null this constructor doesn't throw an {@code Exception}, but later
+     * calls to some methods might throw a {@code NullPointerException}.
      * 
      * @param string
-     *            the string to be tokenized
+     *            the string to be tokenized.
      * @param delimiters
-     *            the delimiters to use
+     *            the delimiters to use.
      * @param returnDelimiters
-     *            true to return each delimiter as a token
+     *            {@code true} to return each delimiter as a token.
      */
     public StringTokenizer(String string, String delimiters,
             boolean returnDelimiters) {
@@ -86,8 +167,8 @@
     /**
      * Returns the number of unprocessed tokens remaining in the string.
      * 
-     * @return number of tokens that can be retreived before an exception will
-     *         result
+     * @return number of tokens that can be retreived before an {@code
+     *         Exception} will result from a call to {@code nextToken()}.
      */
     public int countTokens() {
         int count = 0;
@@ -110,18 +191,19 @@
     }
 
     /**
-     * Returns true if unprocessed tokens remain.
+     * Returns {@code true} if unprocessed tokens remain. This method is
+     * implemented in order to satisfy the {@code Enumeration} interface.
      * 
-     * @return true if unprocessed tokens remain
+     * @return {@code true} if unprocessed tokens remain.
      */
     public boolean hasMoreElements() {
         return hasMoreTokens();
     }
 
     /**
-     * Returns true if unprocessed tokens remain.
+     * Returns {@code true} if unprocessed tokens remain.
      * 
-     * @return true if unprocessed tokens remain
+     * @return {@code true} if unprocessed tokens remain.
      */
     public boolean hasMoreTokens() {
         if (delimiters == null) {
@@ -142,22 +224,23 @@
     }
 
     /**
-     * Returns the next token in the string as an Object.
+     * Returns the next token in the string as an {@code Object}. This method is
+     * implemented in order to satisfy the {@code Enumeration} interface.
      * 
-     * @return next token in the string as an Object
-     * @exception NoSuchElementException
-     *                if no tokens remain
+     * @return next token in the string as an {@code Object}
+     * @throws NoSuchElementException
+     *                if no tokens remain.
      */
     public Object nextElement() {
         return nextToken();
     }
 
     /**
-     * Returns the next token in the string as a String.
+     * Returns the next token in the string as a {@code String}.
      * 
-     * @return next token in the string as a String
-     * @exception NoSuchElementException
-     *                if no tokens remain
+     * @return next token in the string as a {@code String}.
+     * @throws NoSuchElementException
+     *                if no tokens remain.
      */
     public String nextToken() {
         if (delimiters == null) {
@@ -190,14 +273,14 @@
     }
 
     /**
-     * Returns the next token in the string as a String. The delimiters used are
-     * changed to the specified delimiters.
+     * Returns the next token in the string as a {@code String}. The delimiters
+     * used are changed to the specified delimiters.
      * 
      * @param delims
-     *            the new delimiters to use
-     * @return next token in the string as a String
-     * @exception NoSuchElementException
-     *                if no tokens remain
+     *            the new delimiters to use.
+     * @return next token in the string as a {@code String}.
+     * @throws NoSuchElementException
+     *                if no tokens remain.
      */
     public String nextToken(String delims) {
         this.delimiters = delims;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimeZone.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimeZone.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimeZone.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/TimeZone.java Thu May  7 21:43:41 2009
@@ -24,22 +24,53 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * TimeZone is an abstract class which represents a local time zone and its
- * daylight savings time rules. Subclasses support a particular calendar type,
- * such as the gregorian calendar.
- * 
- * Please note the type returned by factory methods, i.e.
- * <code>getDefault()</code> and <code>getTimeZone(String)</code>, is
- * implementation dependent, so that it may introduce serialization
- * incompatibility issue between different implementations. Harmony returns
- * instance of {@link SimpleTimeZone SimpleTimeZone} so that the bytes
- * serialized by Harmony can be deserialized on other implementation
- * successfully, but the reverse compatibility cannot be guaranteed.
- * 
+ * {@code TimeZone} represents a time zone offset, taking into account
+ * daylight savings.
+ * <p>
+ * Typically, you get a {@code TimeZone} using {@code getDefault}
+ * which creates a {@code TimeZone} based on the time zone where the
+ * program is running. For example, for a program running in Japan,
+ * {@code getDefault} creates a {@code TimeZone} object based on
+ * Japanese Standard Time.
+ * <p>
+ * You can also get a {@code TimeZone} using {@code getTimeZone}
+ * along with a time zone ID. For instance, the time zone ID for the U.S.
+ * Pacific Time zone is "America/Los_Angeles". So, you can get a U.S. Pacific
+ * Time {@code TimeZone} object with the following: <blockquote>
+ *
+ * <pre>
+ * TimeZone tz = TimeZone.getTimeZone(&quot;America/Los_Angeles&quot;);
+ * </pre>
+ *
+ * </blockquote> You can use the {@code getAvailableIDs} method to iterate
+ * through all the supported time zone IDs. You can then choose a supported ID
+ * to get a {@code TimeZone}. If the time zone you want is not
+ * represented by one of the supported IDs, then you can create a custom time
+ * zone ID with the following syntax: <blockquote>
+ *
+ * <pre>
+ * GMT[+|-]hh[[:]mm]
+ * </pre>
+ *
+ * </blockquote> For example, you might specify GMT+14:00 as a custom time zone
+ * ID. The {@code TimeZone} that is returned when you specify a custom
+ * time zone ID does not include daylight savings time.
+ * <p>
+ * For compatibility with JDK 1.1.x, some other three-letter time zone IDs (such
+ * as "PST", "CTT", "AST") are also supported. However, <strong>their use is
+ * deprecated</strong> because the same abbreviation is often used for multiple
+ * time zones (for example, "CST" could be U.S. "Central Standard Time" and
+ * "China Standard Time"), and the Java platform can then only recognize one of
+ * them.
+ * <p>
+ * Please note the type returned by factory methods, i.e. {@code getDefault()}
+ * and {@code getTimeZone(String)}, is implementation dependent, so it may
+ * introduce serialization incompatibility issues between different
+ * implementations.
+ *
  * @see GregorianCalendar
  * @see SimpleTimeZone
  */
-
 public abstract class TimeZone implements Serializable, Cloneable {
     private static final long serialVersionUID = 3581463369166924961L;
 
@@ -93,17 +124,15 @@
 
     /**
      * Constructs a new instance of this class.
-     * 
      */
     public TimeZone() {
     }
 
     /**
-     * Answers a new TimeZone with the same ID, rawOffset and daylight savings
-     * time rules as this TimeZone.
-     * 
-     * @return a shallow copy of this TimeZone
-     * 
+     * Returns a new {@code TimeZone} with the same ID, {@code rawOffset} and daylight savings
+     * time rules as this {@code TimeZone}.
+     *
+     * @return a shallow copy of this {@code TimeZone}.
      * @see java.lang.Cloneable
      */
     @Override
@@ -117,9 +146,10 @@
     }
 
     /**
-     * Gets the available time zone IDs.
+     * Gets the available time zone IDs. Any one of these IDs can be passed to
+     * {@code get()} to create the corresponding {@code TimeZone} instance.
      * 
-     * @return an array of time zone ID strings
+     * @return an array of time zone ID strings.
      */
     public static synchronized String[] getAvailableIDs() {
         return com.ibm.icu.util.TimeZone.getAvailableIDs();
@@ -127,11 +157,12 @@
 
     /**
      * Gets the available time zone IDs which match the specified offset from
-     * GMT.
+     * GMT. Any one of these IDs can be passed to {@code get()} to create the corresponding
+     * {@code TimeZone} instance.
      * 
      * @param offset
-     *            the offset from GMT in milliseconds
-     * @return an array of time zone ID strings
+     *            the offset from GMT in milliseconds.
+     * @return an array of time zone ID strings.
      */
     public static synchronized String[] getAvailableIDs(int offset) {
         String[] availableIDs = com.ibm.icu.util.TimeZone.getAvailableIDs();
@@ -153,7 +184,7 @@
     /**
      * Gets the default time zone.
      * 
-     * @return the default time zone
+     * @return the default time zone.
      */
     public static synchronized TimeZone getDefault() {
         if (Default == null) {
@@ -163,56 +194,58 @@
     }
 
     /**
-     * Gets the LONG name for this TimeZone for the default Locale in standard
+     * Gets the LONG name for this {@code TimeZone} for the default {@code Locale} in standard
      * time. If the name is not available, the result is in the format
-     * GMT[+-]hh:mm.
+     * {@code GMT[+-]hh:mm}.
      * 
-     * @return the TimeZone name
+     * @return the {@code TimeZone} name.
      */
     public final String getDisplayName() {
         return getDisplayName(false, LONG, Locale.getDefault());
     }
 
     /**
-     * Gets the LONG name for this TimeZone for the specified Locale in standard
+     * Gets the LONG name for this {@code TimeZone} for the specified {@code Locale} in standard
      * time. If the name is not available, the result is in the format
-     * GMT[+-]hh:mm.
+     * {@code GMT[+-]hh:mm}.
      * 
      * @param locale
-     *            the Locale
-     * @return the TimeZone name
+     *            the {@code Locale}.
+     * @return the {@code TimeZone} name.
      */
     public final String getDisplayName(Locale locale) {
         return getDisplayName(false, LONG, locale);
     }
 
     /**
-     * Gets the specified style of name (LONG or SHORT) for this TimeZone for
-     * the default Locale in either standard or daylight time as specified. If
-     * the name is not available, the result is in the format GMT[+-]hh:mm.
+     * Gets the specified style of name ({@code LONG} or {@code SHORT}) for this {@code TimeZone} for
+     * the default {@code Locale} in either standard or daylight time as specified. If
+     * the name is not available, the result is in the format {@code GMT[+-]hh:mm}.
      * 
      * @param daylightTime
-     *            true for daylight time, false for standard time
+     *            {@code true} for daylight time, {@code false} for standard
+     *            time.
      * @param style
-     *            Either LONG or SHORT
-     * @return the TimeZone name
+     *            either {@code LONG} or {@code SHORT}.
+     * @return the {@code TimeZone} name.
      */
     public final String getDisplayName(boolean daylightTime, int style) {
         return getDisplayName(daylightTime, style, Locale.getDefault());
     }
 
     /**
-     * Gets the specified style of name (LONG or SHORT) for this TimeZone for
-     * the specified Locale in either standard or daylight time as specified. If
-     * the name is not available, the result is in the format GMT[+-]hh:mm.
+     * Gets the specified style of name ({@code LONG} or {@code SHORT}) for this {@code TimeZone} for
+     * the specified {@code Locale} in either standard or daylight time as specified. If
+     * the name is not available, the result is in the format {@code GMT[+-]hh:mm}.
      * 
      * @param daylightTime
-     *            true for daylight time, false for standard time
+     *            {@code true} for daylight time, {@code false} for standard
+     *            time.
      * @param style
-     *            Either LONG or SHORT
+     *            either LONG or SHORT.
      * @param locale
-     *            the Locale
-     * @return the TimeZone name
+     *            either {@code LONG} or {@code SHORT}.
+     * @return the {@code TimeZone} name.
      */
     public String getDisplayName(boolean daylightTime, int style, Locale locale) {
         if(icuTimeZone == null || !ID.equals(icuTimeZone.getID())){
@@ -223,16 +256,16 @@
     }
 
     /**
-     * Gets the ID of this TimeZone.
+     * Gets the ID of this {@code TimeZone}.
      * 
-     * @return the time zone ID string
+     * @return the time zone ID string.
      */
     public String getID() {
         return ID;
     }
 
     /**
-     * Gets the daylight savings offset in milliseconds for this TimeZone.
+     * Gets the daylight savings offset in milliseconds for this {@code TimeZone}.
      * <p>
      * This implementation returns 3600000 (1 hour), or 0 if the time zone does
      * not observe daylight savings.
@@ -241,9 +274,8 @@
      * hour.
      * <p>
      * 
-     * @return the daylight savings offset in milliseconds if this TimeZone
+     * @return the daylight savings offset in milliseconds if this {@code TimeZone}
      *         observes daylight savings, zero otherwise.
-     * 
      */
     public int getDSTSavings() {
         if (useDaylightTime()) {
@@ -253,13 +285,13 @@
     }
 
     /**
-     * Gets the offset from GMT of this TimeZone for the specified date. The
+     * Gets the offset from GMT of this {@code TimeZone} for the specified date. The
      * offset includes daylight savings time if the specified date is within the
      * daylight savings time period.
      * 
      * @param time
      *            the date in milliseconds since January 1, 1970 00:00:00 GMT
-     * @return the offset from GMT in milliseconds
+     * @return the offset from GMT in milliseconds.
      */
     public int getOffset(long time) {
         if (inDaylightTime(new Date(time))) {
@@ -269,42 +301,42 @@
     }
 
     /**
-     * Gets the offset from GMT of this TimeZone for the specified date and
+     * Gets the offset from GMT of this {@code TimeZone} for the specified date and
      * time. The offset includes daylight savings time if the specified date and
      * time are within the daylight savings time period.
      * 
      * @param era
-     *            the GregorianCalendar era, either GregorianCalendar.BC or
-     *            GregorianCalendar.AD
+     *            the {@code GregorianCalendar} era, either {@code GregorianCalendar.BC} or
+     *            {@code GregorianCalendar.AD}.
      * @param year
-     *            the year
+     *            the year.
      * @param month
-     *            the Calendar month
+     *            the {@code Calendar} month.
      * @param day
-     *            the day of the month
+     *            the day of the month.
      * @param dayOfWeek
-     *            the Calendar day of the week
+     *            the {@code Calendar} day of the week.
      * @param time
-     *            the time of day in milliseconds
-     * @return the offset from GMT in milliseconds
+     *            the time of day in milliseconds.
+     * @return the offset from GMT in milliseconds.
      */
     abstract public int getOffset(int era, int year, int month, int day,
             int dayOfWeek, int time);
 
     /**
-     * Gets the offset for standard time from GMT for this TimeZone.
+     * Gets the offset for standard time from GMT for this {@code TimeZone}.
      * 
-     * @return the offset from GMT in milliseconds
+     * @return the offset from GMT in milliseconds.
      */
     abstract public int getRawOffset();
 
     /**
-     * Gets the time zone with the specified ID.
+     * Gets the {@code TimeZone} with the specified ID.
      * 
      * @param name
-     *            a time zone string ID
-     * @return the time zone with the specified ID or null if a time zone with
-     *         the specified ID does not exist
+     *            a time zone string ID.
+     * @return the {@code TimeZone} with the specified ID or null if no {@code TimeZone} with
+     *         the specified ID exists.
      */
     public static synchronized TimeZone getTimeZone(String name) {
         if (AvailableZones == null) {
@@ -382,12 +414,13 @@
     }
 
     /**
-     * Answers if the specified TimeZone has the same raw offset as this
-     * TimeZone.
+     * Returns whether the specified {@code TimeZone} has the same raw offset as this
+     * {@code TimeZone}.
      * 
      * @param zone
-     *            a TimeZone
-     * @return true when the TimeZones have the same raw offset, false otherwise
+     *            a {@code TimeZone}.
+     * @return {@code true} when the {@code TimeZone} have the same raw offset, {@code false}
+     *         otherwise.
      */
     public boolean hasSameRules(TimeZone zone) {
         if (zone == null) {
@@ -397,13 +430,13 @@
     }
 
     /**
-     * Answers if the specified Date is in the daylight savings time period for
-     * this TimeZone.
+     * Returns whether the specified {@code Date} is in the daylight savings time period for
+     * this {@code TimeZone}.
      * 
      * @param time
-     *            a Date
-     * @return true when the Date is in the daylight savings time period, false
-     *         otherwise
+     *            a {@code Date}.
+     * @return {@code true} when the {@code Date} is in the daylight savings time period, {@code false}
+     *         otherwise.
      */
     abstract public boolean inDaylightTime(Date time);
 
@@ -419,10 +452,13 @@
     }
 
     /**
-     * Sets the default time zone.
+     * Sets the default time zone. If passed {@code null}, then the next
+     * time {@link #getDefault} is called, the default time zone will be
+     * determined. This behavior is slightly different than the canonical
+     * description of this method, but it follows the spirit of it.
      * 
      * @param timezone
-     *            a TimeZone object
+     *            a {@code TimeZone} object.
      */
     public static synchronized void setDefault(TimeZone timezone) {
         if (timezone != null) {
@@ -494,10 +530,10 @@
     }
 
     /**
-     * Sets the ID of this TimeZone.
+     * Sets the ID of this {@code TimeZone}.
      * 
      * @param name
-     *            a string which is the time zone ID
+     *            a string which is the time zone ID.
      */
     public void setID(String name) {
         if (name == null) {
@@ -507,18 +543,18 @@
     }
 
     /**
-     * Sets the offset for standard time from GMT for this TimeZone.
+     * Sets the offset for standard time from GMT for this {@code TimeZone}.
      * 
      * @param offset
-     *            the offset from GMT in milliseconds
+     *            the offset from GMT in milliseconds.
      */
     abstract public void setRawOffset(int offset);
 
     /**
-     * Answers if this TimeZone has a daylight savings time period.
+     * Returns whether this {@code TimeZone} has a daylight savings time period.
      * 
-     * @return true if this time zone has a daylight savings time period, false
-     *         otherwise
+     * @return {@code true} if this {@code TimeZone} has a daylight savings time period, {@code false}
+     *         otherwise.
      */
     abstract public boolean useDaylightTime();
 

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Timer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Timer.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Timer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Timer.java Thu May  7 21:43:41 2009
@@ -20,23 +20,36 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * Timers are used to schedule jobs for execution in a background process. A
+ * {@code Timer}s are used to schedule jobs for execution in a background process. A
  * single thread is used for the scheduling and this thread has the option of
- * being a daemon thread. By calling <code>cancel</code> you can terminate a
- * timer and it's associated thread. All tasks which are scheduled to run after
+ * being a daemon thread. By calling {@code cancel} you can terminate a
+ * {@code Timer} and its associated thread. All tasks which are scheduled to run after
  * this point are cancelled. Tasks are executed sequentially but are subject to
  * the delays from other tasks run methods. If a specific task takes an
  * excessive amount of time to run it may impact the time at which subsequent
  * tasks may run.
  * <p>
  *
- * The Timer task does not offer any guarantees about the real-time nature of
- * scheduling tasks as it's underlying implementation relies on the
- * <code>Object.wait(long)</code> method.
+ * The {@code TimerTask} does not offer any guarantees about the real-time nature of
+ * scheduling tasks as its underlying implementation relies on the
+ * {@code Object.wait(long)} method.
  * <p>
- *
- * Multiple threads can share a single Timer without the need for their own
+ * Multiple threads can share a single {@code Timer} without the need for their own
  * synchronization.
+ * <p>
+ * A {@code Timer} can be set to schedule tasks either at a fixed rate or
+ * with a fixed period. Fixed-period execution is the default.
+ * <p>
+ * The difference between fixed-rate and fixed-period execution
+ * is the following:  With fixed-rate execution, the start time of each
+ * successive run of the task is scheduled in absolute terms without regard for when the previous
+ * task run actually took place. This can result in a series of bunched-up runs
+ * (one launched immediately after another) if busy resources or other
+ * system delays prevent the {@code Timer} from firing for an extended time.
+ * With fixed-period execution, each successive run of the
+ * task is scheduled relative to the start time of the previous run of the
+ * task, so two runs of the task are never fired closer together in time than
+ * the specified {@code period}.
  *
  * @see TimerTask
  * @see java.lang.Object#wait(long)
@@ -168,7 +181,7 @@
 
         /**
          * Vector consists of scheduled events, sorted according to
-         * <code>when</code> field of TaskScheduled object.
+         * {@code when} field of TaskScheduled object.
          */
         private TimerHeap tasks = new TimerHeap();
 
@@ -328,69 +341,61 @@
     };
 
     /**
-     * Creates a new Timer which may be specified to be run as a Daemon Thread.
+     * Creates a new {@code Timer} which may be specified to be run as a daemon thread.
      *
      * @param isDaemon
-     *            true if Timers thread should be a daemon thread.
+     *            {@code true} if the {@code Timer}'s thread should be a daemon thread.
      */
     public Timer(boolean isDaemon) {
         impl = new TimerImpl(isDaemon);
     }
 
     /**
-     * Creates a new non-daemon Timer.
+     * Creates a new non-daemon {@code Timer}.
      */
     public Timer() {
         impl = new TimerImpl(false);
     }
 
     /**
-     * Create a new timer with the given name and daemon status.
-     *
-     * The name is given the timer's background thread and if the flag is true
-     * the thread is run as a daemon.
+     * Creates a new named {@code Timer} which may be specified to be run as a
+     * daemon thread.
      *
      * @param name
-     *            a name to associate with the timer thread.
+     *            the name of the {@code Timer}.
      * @param isDaemon
-     *            true if the timer thread should be a daemon, or false if it is
-     *            a regular thread that prevents the application terminating.
+     *            true if {@code Timer}'s thread should be a daemon thread.
      */
     public Timer(String name, boolean isDaemon) {
         impl = new TimerImpl(name, isDaemon);
     }
 
     /**
-     * Create a new timer whose thread has the given name.
-     *
-     * The name is given the timer's background thread, that is not run as a
-     * daemon.
+     * Creates a new named {@code Timer} which does not run as a daemon thread.
      *
      * @param name
-     *            a name to associate with the timer thread.
+     *            the name of the Timer.
      */
     public Timer(String name) {
         impl = new TimerImpl(name, false);
     }
 
     /**
-     * Cancels the Timer and removed any scheduled tasks. If there is a
-     * currently running task it is not effected. No more tasks may be scheduled
-     * on this Timer. Subsequent calls do nothing.
+     * Cancels the {@code Timer} and removes any scheduled tasks. If there is a
+     * currently running task it is not affected. No more tasks may be scheduled
+     * on this {@code Timer}. Subsequent calls do nothing.
      */
     public void cancel() {
         impl.cancel();
     }
 
     /**
-     * Purging the timer eagerly removes cancelled tasks.
-     *
-     * When a large number of tasks have been cancelled it may be helpful to
-     * explicitly purge them from the timer rather than let them be removed
-     * during normal expiry processing. This is a housekeeping task that does
-     * not affect the timer's schedule tasks.
+     * Removes all canceled tasks from the task queue. If there are no
+     * other references on the tasks, then after this call they are free
+     * to be garbage collected.
      *
-     * @return the number of tasks that were purged.
+     * @return the number of canceled tasks that were removed from the task
+     *         queue.
      */
     public int purge() {
         synchronized (impl) {
@@ -399,19 +404,18 @@
     }
 
     /**
-     * Schedule a task for single execution. If when is less than the current
-     * time, it will be scheduled to executed as soon as possible.
+     * Schedule a task for single execution. If {@code when} is less than the
+     * current time, it will be scheduled to be executed as soon as possible.
      *
      * @param task
-     *            The task to schedule
+     *            the task to schedule.
      * @param when
-     *            Time of execution
-     *
-     * @exception IllegalArgumentException
-     *                if when.getTime() < 0
-     * @exception IllegalStateException
-     *                if the timer has been cancelled, the task has been
-     *                scheduled or cancelled.
+     *            time of execution.
+     * @throws IllegalArgumentException
+     *                if {@code when.getTime() < 0}.
+     * @throws IllegalStateException
+     *                if the {@code Timer} has been canceled, or if the task has been
+     *                scheduled or canceled.
      */
     public void schedule(TimerTask task, Date when) {
         if (when.getTime() < 0) {
@@ -422,18 +426,17 @@
     }
 
     /**
-     * Schedule a task for single execution after a specific delay.
+     * Schedule a task for single execution after a specified delay.
      *
      * @param task
-     *            The task to schedule
+     *            the task to schedule.
      * @param delay
-     *            Amount of time before execution
-     *
-     * @exception IllegalArgumentException
-     *                if delay < 0
-     * @exception IllegalStateException
-     *                if the timer has been cancelled, the task has been
-     *                scheduled or cancelled.
+     *            amount of time before execution.
+     * @throws IllegalArgumentException
+     *                if {@code delay < 0}.
+     * @throws IllegalStateException
+     *                if the {@code Timer} has been canceled, or if the task has been
+     *                scheduled or canceled.
      */
     public void schedule(TimerTask task, long delay) {
         if (delay < 0) {
@@ -443,20 +446,19 @@
     }
 
     /**
-     * Schedule a task for repeated fix-delay execution after a specific delay.
+     * Schedule a task for repeated fixed-delay execution after a specific delay.
      *
      * @param task
-     *            The task to schedule
+     *            the task to schedule.
      * @param delay
-     *            Amount of time before first execution
+     *            amount of time before first execution.
      * @param period
-     *            Amount of time between subsequent executions
-     *
-     * @exception IllegalArgumentException
-     *                if delay < 0 or period < 0
-     * @exception IllegalStateException
-     *                if the timer has been cancelled, the task has been
-     *                scheduled or cancelled.
+     *            amount of time between subsequent executions.
+     * @throws IllegalArgumentException
+     *                if {@code delay < 0} or {@code period < 0}.
+     * @throws IllegalStateException
+     *                if the {@code Timer} has been canceled, or if the task has been
+     *                scheduled or canceled.
      */
     public void schedule(TimerTask task, long delay, long period) {
         if (delay < 0 || period <= 0) {
@@ -466,21 +468,20 @@
     }
 
     /**
-     * Schedule a task for repeated fix-delay execution after a specific time
+     * Schedule a task for repeated fixed-delay execution after a specific time
      * has been reached.
      *
      * @param task
-     *            The task to schedule
+     *            the task to schedule.
      * @param when
-     *            Time of first execution
+     *            time of first execution.
      * @param period
-     *            Amount of time between subsequent executions
-     *
-     * @exception IllegalArgumentException
-     *                if when.getTime() < 0 or period < 0
-     * @exception IllegalStateException
-     *                if the timer has been cancelled, the task has been
-     *                scheduled or cancelled.
+     *            amount of time between subsequent executions.
+     * @throws IllegalArgumentException
+     *                if {@code when.getTime() < 0} or {@code period < 0}.
+     * @throws IllegalStateException
+     *                if the {@code Timer} has been canceled, or if the task has been
+     *                scheduled or canceled.
      */
     public void schedule(TimerTask task, Date when, long period) {
         if (period <= 0 || when.getTime() < 0) {
@@ -492,22 +493,19 @@
 
     /**
      * Schedule a task for repeated fixed-rate execution after a specific delay
-     * has been happened. The difference of fixed-rate is that it may bunch up
-     * subsequent task runs to try to get the task repeating at it's desired
-     * time.
+     * has passed.
      *
      * @param task
-     *            The task to schedule
+     *            the task to schedule.
      * @param delay
-     *            Amount of time before first execution
+     *            amount of time before first execution.
      * @param period
-     *            Amount of time between subsequent executions
-     *
-     * @exception IllegalArgumentException
-     *                if delay < 0 or period < 0
-     * @exception IllegalStateException
-     *                if the timer has been cancelled, the task has been
-     *                scheduled or cancelled.
+     *            amount of time between subsequent executions.
+     * @throws IllegalArgumentException
+     *                if {@code delay < 0} or {@code period < 0}.
+     * @throws IllegalStateException
+     *                if the {@code Timer} has been canceled, or if the task has been
+     *                scheduled or canceled.
      */
     public void scheduleAtFixedRate(TimerTask task, long delay, long period) {
         if (delay < 0 || period <= 0) {
@@ -518,22 +516,19 @@
 
     /**
      * Schedule a task for repeated fixed-rate execution after a specific time
-     * has been reached. The difference of fixed-rate is that it may bunch up
-     * subsequent task runs to try to get the task repeating at it's desired
-     * time.
+     * has been reached.
      *
      * @param task
-     *            The task to schedule
+     *            the task to schedule.
      * @param when
-     *            Time of first execution
+     *            time of first execution.
      * @param period
-     *            Amount of time between subsequent executions
-     *
-     * @exception IllegalArgumentException
-     *                if when.getTime() < 0 or period < 0
-     * @exception IllegalStateException
-     *                if the timer has been cancelled, the task has been
-     *                scheduled or cancelled.
+     *            amount of time between subsequent executions.
+     * @throws IllegalArgumentException
+     *                if {@code when.getTime() < 0} or {@code period < 0}.
+     * @throws IllegalStateException
+     *                if the {@code Timer} has been canceled, or if the task has been
+     *                scheduled or canceled.
      */
     public void scheduleAtFixedRate(TimerTask task, Date when, long period) {
         if (period <= 0 || when.getTime() < 0) {



Mime
View raw message