commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject svn commit: r1077933 - /commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/time/DateUtils.java
Date Fri, 04 Mar 2011 13:29:02 GMT
Author: scolebourne
Date: Fri Mar  4 13:29:01 2011
New Revision: 1077933

URL: http://svn.apache.org/viewvc?rev=1077933&view=rev
Log:
Javadoc

Modified:
    commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/time/DateUtils.java

Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/time/DateUtils.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/time/DateUtils.java?rev=1077933&r1=1077932&r2=1077933&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/time/DateUtils.java (original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/time/DateUtils.java Fri
Mar  4 13:29:01 2011
@@ -39,8 +39,6 @@ import java.util.TimeZone;
  * Since a date without a year is not a valid date, you have to decide in what
  * kind of date-field you want your result, for instance milliseconds or days.
  * </p>
- *   
- *   
  *
  * @author Apache Software Foundation
  * @author <a href="mailto:sergek@lokitech.com">Serge Knystautas</a>
@@ -53,9 +51,9 @@ import java.util.TimeZone;
  * @version $Id$
  */
 public class DateUtils {
-    
+
     /**
-     * The UTC time zone  (often referred to as GMT).
+     * The UTC time zone (often referred to as GMT).
      */
     public static final TimeZone UTC_TIME_ZONE = TimeZone.getTimeZone("GMT");
     /**
@@ -101,55 +99,47 @@ public class DateUtils {
      * A week range, starting on Sunday.
      */
     public static final int RANGE_WEEK_SUNDAY = 1;
-
     /**
      * A week range, starting on Monday.
      */
     public static final int RANGE_WEEK_MONDAY = 2;
-
     /**
      * A week range, starting on the day focused.
      */
     public static final int RANGE_WEEK_RELATIVE = 3;
-
     /**
      * A week range, centered around the day focused.
      */
     public static final int RANGE_WEEK_CENTER = 4;
-
     /**
      * A month range, the week starting on Sunday.
      */
     public static final int RANGE_MONTH_SUNDAY = 5;
-
     /**
      * A month range, the week starting on Monday.
      */
     public static final int RANGE_MONTH_MONDAY = 6;
-    
+
     /**
-     * Constant marker for truncating 
+     * Constant marker for truncating.
      * @since 3.0
      */
     public static final int MODIFY_TRUNCATE = 0;
-
     /**
-     * Constant marker for rounding
+     * Constant marker for rounding.
      * @since 3.0
      */
     public static final int MODIFY_ROUND = 1;
-    
     /**
-     * Constant marker for ceiling
+     * Constant marker for ceiling.
      * @since 3.0
      */
-    public static final int MODIFY_CEILING= 2;
-    
+    public static final int MODIFY_CEILING = 2;
 
     /**
-     * <p><code>DateUtils</code> instances should NOT be constructed in
-     * standard programming. Instead, the class should be used as
-     * <code>DateUtils.parse(str);</code>.</p>
+     * <p>{@code DateUtils} instances should NOT be constructed in
+     * standard programming. Instead, the static methods on the class should
+     * be used, such as {@code DateUtils.parseDate(str);}.</p>
      *
      * <p>This constructor is public to permit tools that require a JavaBean
      * instance to operate.</p>
@@ -323,8 +313,8 @@ public class DateUtils {
      * @throws ParseException if none of the date patterns were suitable
      * @see java.util.Calender#isLenient()
      */
-    private static Date parseDateWithLeniency(String str, String[] parsePatterns,
-            boolean lenient) throws ParseException {
+    private static Date parseDateWithLeniency(
+            String str, String[] parsePatterns, boolean lenient) throws ParseException {
         if (str == null || parsePatterns == null) {
             throw new IllegalArgumentException("Date and Patterns must not be null");
         }
@@ -361,11 +351,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Adds a number of years to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount  the amount to add, may be negative
-     * @return the new date object with the amount added
+     * @return the new {@code Date} with the amount added
      * @throws IllegalArgumentException if the date is null
      */
     public static Date addYears(Date date, int amount) {
@@ -375,11 +365,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Adds a number of months to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount  the amount to add, may be negative
-     * @return the new date object with the amount added
+     * @return the new {@code Date} with the amount added
      * @throws IllegalArgumentException if the date is null
      */
     public static Date addMonths(Date date, int amount) {
@@ -389,11 +379,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Adds a number of weeks to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount  the amount to add, may be negative
-     * @return the new date object with the amount added
+     * @return the new {@code Date} with the amount added
      * @throws IllegalArgumentException if the date is null
      */
     public static Date addWeeks(Date date, int amount) {
@@ -403,11 +393,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Adds a number of days to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount  the amount to add, may be negative
-     * @return the new date object with the amount added
+     * @return the new {@code Date} with the amount added
      * @throws IllegalArgumentException if the date is null
      */
     public static Date addDays(Date date, int amount) {
@@ -417,11 +407,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Adds a number of hours to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount  the amount to add, may be negative
-     * @return the new date object with the amount added
+     * @return the new {@code Date} with the amount added
      * @throws IllegalArgumentException if the date is null
      */
     public static Date addHours(Date date, int amount) {
@@ -431,11 +421,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Adds a number of minutes to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount  the amount to add, may be negative
-     * @return the new date object with the amount added
+     * @return the new {@code Date} with the amount added
      * @throws IllegalArgumentException if the date is null
      */
     public static Date addMinutes(Date date, int amount) {
@@ -445,11 +435,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Adds a number of seconds to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount  the amount to add, may be negative
-     * @return the new date object with the amount added
+     * @return the new {@code Date} with the amount added
      * @throws IllegalArgumentException if the date is null
      */
     public static Date addSeconds(Date date, int amount) {
@@ -459,11 +449,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Adds a number of milliseconds to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount  the amount to add, may be negative
-     * @return the new date object with the amount added
+     * @return the new {@code Date} with the amount added
      * @throws IllegalArgumentException if the date is null
      */
     public static Date addMilliseconds(Date date, int amount) {
@@ -473,12 +463,12 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Adds to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param calendarField  the calendar field to add to
      * @param amount  the amount to add, may be negative
-     * @return the new date object with the amount added
+     * @return the new {@code Date} with the amount added
      * @throws IllegalArgumentException if the date is null
      */
     private static Date add(Date date, int calendarField, int amount) {
@@ -494,11 +484,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Sets the years field to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount the amount to set
-     * @return a new Date object set with the specified value
+     * @return a new {@code Date} set with the specified value
      * @throws IllegalArgumentException if the date is null
      * @since 2.4
      */
@@ -509,11 +499,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Sets the months field to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount the amount to set
-     * @return a new Date object set with the specified value
+     * @return a new {@code Date} set with the specified value
      * @throws IllegalArgumentException if the date is null
      * @since 2.4
      */
@@ -524,11 +514,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Sets the day of month field to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount the amount to set
-     * @return a new Date object set with the specified value
+     * @return a new {@code Date} set with the specified value
      * @throws IllegalArgumentException if the date is null
      * @since 2.4
      */
@@ -540,11 +530,11 @@ public class DateUtils {
     /**
      * Sets the hours field to a date returning a new object.  Hours range 
      * from  0-23.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount the amount to set
-     * @return a new Date object set with the specified value
+     * @return a new {@code Date} set with the specified value
      * @throws IllegalArgumentException if the date is null
      * @since 2.4
      */
@@ -555,11 +545,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Sets the minute field to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount the amount to set
-     * @return a new Date object set with the specified value
+     * @return a new {@code Date} set with the specified value
      * @throws IllegalArgumentException if the date is null
      * @since 2.4
      */
@@ -570,11 +560,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Sets the seconds field to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount the amount to set
-     * @return a new Date object set with the specified value
+     * @return a new {@code Date} set with the specified value
      * @throws IllegalArgumentException if the date is null
      * @since 2.4
      */
@@ -585,11 +575,11 @@ public class DateUtils {
     //-----------------------------------------------------------------------
     /**
      * Sets the miliseconds field to a date returning a new object.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
      * @param amount the amount to set
-     * @return a new Date object set with the specified value
+     * @return a new {@code Date} set with the specified value
      * @throws IllegalArgumentException if the date is null
      * @since 2.4
      */
@@ -601,12 +591,12 @@ public class DateUtils {
     /**
      * Sets the specified field to a date returning a new object.  
      * This does not use a lenient calendar.
-     * The original date object is unchanged.
+     * The original {@code Date} is unchanged.
      *
      * @param date  the date, not null
-     * @param calendarField  the calendar field to set the amount to
+     * @param calendarField  the {@code Calendar} field to set the amount to
      * @param amount the amount to set
-     * @return a new Date object set with the specified value
+     * @return a new {@code Date} set with the specified value
      * @throws IllegalArgumentException if the date is null
      * @since 2.4
      */
@@ -624,7 +614,7 @@ public class DateUtils {
 
     //-----------------------------------------------------------------------
     /**
-     * Convert a Date into a Calendar object. 
+     * Convert a {@code Date} into a {@code Calendar}. 
      * 
      * @param date the date to convert to a Calendar
      * @return the created Calendar
@@ -659,11 +649,10 @@ public class DateUtils {
      * </ul>
      * </p>
      * 
-     * @param date  the date to work with
-     * @param field  the field from <code>Calendar</code>
-     *  or <code>SEMI_MONTH</code>
-     * @return the rounded date
-     * @throws IllegalArgumentException if the date is <code>null</code>
+     * @param date  the date to work with, not null
+     * @param field  the field from {@code Calendar} or <code>SEMI_MONTH</code>
+     * @param field  the field from {@code Calendar} or <code>SEMI_MONTH</code>
+     * @return the different rounded date, not null
      * @throws ArithmeticException if the year is over 280 million
      */
     public static Date round(Date date, int field) {
@@ -697,10 +686,9 @@ public class DateUtils {
      * </ul>
      * </p>
      * 
-     * @param date  the date to work with
-     * @param field  the field from <code>Calendar</code>
-     *  or <code>SEMI_MONTH</code>
-     * @return the rounded date (a different object)
+     * @param date  the date to work with, not null
+     * @param field  the field from {@code Calendar} or <code>SEMI_MONTH</code>
+     * @return the different rounded date, not null
      * @throws IllegalArgumentException if the date is <code>null</code>
      * @throws ArithmeticException if the year is over 280 million
      */
@@ -734,13 +722,11 @@ public class DateUtils {
      * </ul>
      * </p>
      * 
-     * @param date  the date to work with, either Date or Calendar
-     * @param field  the field from <code>Calendar</code>
-     *  or <code>SEMI_MONTH</code>
-     * @return the rounded date
+     * @param date  the date to work with, either {@code Date} or {@code Calendar}, not null
+     * @param field  the field from {@code Calendar} or <code>SEMI_MONTH</code>
+     * @return the different rounded date, not null
      * @throws IllegalArgumentException if the date is <code>null</code>
-     * @throws ClassCastException if the object type is not a <code>Date</code>
-     *  or <code>Calendar</code>
+     * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
      * @throws ArithmeticException if the year is over 280 million
      */
     public static Date round(Object date, int field) {
@@ -766,10 +752,9 @@ public class DateUtils {
      * 2002 13:00:00.000.  If this was passed with MONTH, it would
      * return 1 Mar 2002 0:00:00.000.</p>
      * 
-     * @param date  the date to work with
-     * @param field  the field from <code>Calendar</code>
-     *  or <code>SEMI_MONTH</code>
-     * @return the rounded date
+     * @param date  the date to work with, not null
+     * @param field  the field from {@code Calendar} or <code>SEMI_MONTH</code>
+     * @return the different truncated date, not null
      * @throws IllegalArgumentException if the date is <code>null</code>
      * @throws ArithmeticException if the year is over 280 million
      */
@@ -792,10 +777,9 @@ public class DateUtils {
      * 2002 13:00:00.000.  If this was passed with MONTH, it would
      * return 1 Mar 2002 0:00:00.000.</p>
      * 
-     * @param date  the date to work with
-     * @param field  the field from <code>Calendar</code>
-     *  or <code>SEMI_MONTH</code>
-     * @return the rounded date (a different object)
+     * @param date  the date to work with, not null
+     * @param field  the field from {@code Calendar} or <code>SEMI_MONTH</code>
+     * @return the different truncated date, not null
      * @throws IllegalArgumentException if the date is <code>null</code>
      * @throws ArithmeticException if the year is over 280 million
      */
@@ -817,15 +801,11 @@ public class DateUtils {
      * 2002 13:00:00.000.  If this was passed with MONTH, it would
      * return 1 Mar 2002 0:00:00.000.</p>
      * 
-     * @param date  the date to work with, either <code>Date</code>
-     *  or <code>Calendar</code>
-     * @param field  the field from <code>Calendar</code>
-     *  or <code>SEMI_MONTH</code>
-     * @return the rounded date
-     * @throws IllegalArgumentException if the date
-     *  is <code>null</code>
-     * @throws ClassCastException if the object type is not a
-     *  <code>Date</code> or <code>Calendar</code>
+     * @param date  the date to work with, either {@code Date} or {@code Calendar}, not null
+     * @param field  the field from {@code Calendar} or <code>SEMI_MONTH</code>
+     * @return the different truncated date, not null
+     * @throws IllegalArgumentException if the date is <code>null</code>
+     * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
      * @throws ArithmeticException if the year is over 280 million
      */
     public static Date truncate(Object date, int field) {
@@ -851,10 +831,9 @@ public class DateUtils {
      * 2002 14:00:00.000.  If this was passed with MONTH, it would
      * return 1 Apr 2002 0:00:00.000.</p>
      * 
-     * @param date  the date to work with
-     * @param field  the field from <code>Calendar</code>
-     *  or <code>SEMI_MONTH</code>
-     * @return the rounded date
+     * @param date  the date to work with, not null
+     * @param field  the field from {@code Calendar} or <code>SEMI_MONTH</code>
+     * @return the different ceil date, not null
      * @throws IllegalArgumentException if the date is <code>null</code>
      * @throws ArithmeticException if the year is over 280 million
      * @since 2.5
@@ -878,10 +857,9 @@ public class DateUtils {
      * 2002 13:00:00.000.  If this was passed with MONTH, it would
      * return 1 Mar 2002 0:00:00.000.</p>
      * 
-     * @param date  the date to work with
-     * @param field  the field from <code>Calendar</code>
-     *  or <code>SEMI_MONTH</code>
-     * @return the rounded date (a different object)
+     * @param date  the date to work with, not null
+     * @param field  the field from {@code Calendar} or <code>SEMI_MONTH</code>
+     * @return the different ceil date, not null
      * @throws IllegalArgumentException if the date is <code>null</code>
      * @throws ArithmeticException if the year is over 280 million
      * @since 2.5
@@ -904,15 +882,11 @@ public class DateUtils {
      * 2002 13:00:00.000.  If this was passed with MONTH, it would
      * return 1 Mar 2002 0:00:00.000.</p>
      * 
-     * @param date  the date to work with, either <code>Date</code>
-     *  or <code>Calendar</code>
-     * @param field  the field from <code>Calendar</code>
-     *  or <code>SEMI_MONTH</code>
-     * @return the rounded date
-     * @throws IllegalArgumentException if the date
-     *  is <code>null</code>
-     * @throws ClassCastException if the object type is not a
-     *  <code>Date</code> or <code>Calendar</code>
+     * @param date  the date to work with, either {@code Date} or {@code Calendar}, not null
+     * @param field  the field from {@code Calendar} or <code>SEMI_MONTH</code>
+     * @return the different ceil date, not null
+     * @throws IllegalArgumentException if the date is <code>null</code>
+     * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
      * @throws ArithmeticException if the year is over 280 million
      * @since 2.5
      */
@@ -933,7 +907,7 @@ public class DateUtils {
     /**
      * <p>Internal calculation method.</p>
      * 
-     * @param val  the calendar
+     * @param val  the calendar, not null
      * @param field  the field constant
      * @param modType  type to truncate, round or ceiling
      * @throws ArithmeticException if the year is over 280 million
@@ -1097,7 +1071,7 @@ public class DateUtils {
      * {@link DateUtils#RANGE_WEEK_MONDAY},
      * {@link DateUtils#RANGE_WEEK_RELATIVE},
      * {@link DateUtils#RANGE_WEEK_CENTER}
-     * @return the date iterator, which always returns Calendar instances
+     * @return the date iterator, not null, not null
      * @throws IllegalArgumentException if the date is <code>null</code>
      * @throws IllegalArgumentException if the rangeStyle is invalid
      */
@@ -1122,7 +1096,7 @@ public class DateUtils {
      * <p>This method provides an iterator that returns Calendar objects.
      * The days are progressed using {@link Calendar#add(int, int)}.</p>
      *
-     * @param focus  the date to work with
+     * @param focus  the date to work with, not null
      * @param rangeStyle  the style constant to use. Must be one of
      * {@link DateUtils#RANGE_MONTH_SUNDAY}, 
      * {@link DateUtils#RANGE_MONTH_MONDAY},
@@ -1130,7 +1104,7 @@ public class DateUtils {
      * {@link DateUtils#RANGE_WEEK_MONDAY},
      * {@link DateUtils#RANGE_WEEK_RELATIVE},
      * {@link DateUtils#RANGE_WEEK_CENTER}
-     * @return the date iterator
+     * @return the date iterator, not null
      * @throws IllegalArgumentException if the date is <code>null</code>
      * @throws IllegalArgumentException if the rangeStyle is invalid
      */
@@ -1215,15 +1189,12 @@ public class DateUtils {
      * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3,
      * 2002, returning a Calendar instance for each intermediate day.</p>
      *
-     * @param focus  the date to work with, either
-     *  <code>Date</code> or <code>Calendar</code>
+     * @param focus  the date to work with, either {@code Date} or {@code Calendar}, not
null
      * @param rangeStyle  the style constant to use. Must be one of the range
      * styles listed for the {@link #iterator(Calendar, int)} method.
-     * @return the date iterator
-     * @throws IllegalArgumentException if the date
-     *  is <code>null</code>
-     * @throws ClassCastException if the object type is
-     *  not a <code>Date</code> or <code>Calendar</code>
+     * @return the date iterator, not null
+     * @throws IllegalArgumentException if the date is <code>null</code>
+     * @throws ClassCastException if the object type is not a {@code Date} or {@code Calendar}
      */
     public static Iterator<?> iterator(Object focus, int rangeStyle) {
         if (focus == null) {
@@ -1265,7 +1236,7 @@ public class DateUtils {
      * </p>
      * 
      * @param date the date to work with, not null
-     * @param fragment the Calendar field part of date to calculate 
+     * @param fragment the {@code Calendar} field part of date to calculate 
      * @return number of milliseconds within the fragment of date
      * @throws IllegalArgumentException if the date is <code>null</code> or
      * fragment is not supported
@@ -1305,7 +1276,7 @@ public class DateUtils {
      * </p>
      * 
      * @param date the date to work with, not null
-     * @param fragment the Calendar field part of date to calculate 
+     * @param fragment the {@code Calendar} field part of date to calculate 
      * @return number of seconds within the fragment of date
      * @throws IllegalArgumentException if the date is <code>null</code> or
      * fragment is not supported
@@ -1345,7 +1316,7 @@ public class DateUtils {
      * </p>
      * 
      * @param date the date to work with, not null
-     * @param fragment the Calendar field part of date to calculate 
+     * @param fragment the {@code Calendar} field part of date to calculate 
      * @return number of minutes within the fragment of date
      * @throws IllegalArgumentException if the date is <code>null</code> or 
      * fragment is not supported
@@ -1385,7 +1356,7 @@ public class DateUtils {
      * </p>
      * 
      * @param date the date to work with, not null
-     * @param fragment the Calendar field part of date to calculate 
+     * @param fragment the {@code Calendar} field part of date to calculate 
      * @return number of hours within the fragment of date
      * @throws IllegalArgumentException if the date is <code>null</code> or 
      * fragment is not supported
@@ -1425,7 +1396,7 @@ public class DateUtils {
      * </p>
      * 
      * @param date the date to work with, not null
-     * @param fragment the Calendar field part of date to calculate 
+     * @param fragment the {@code Calendar} field part of date to calculate 
      * @return number of days  within the fragment of date
      * @throws IllegalArgumentException if the date is <code>null</code> or 
      * fragment is not supported
@@ -1465,7 +1436,7 @@ public class DateUtils {
      * </p>
      * 
      * @param calendar the calendar to work with, not null
-     * @param fragment the Calendar field part of calendar to calculate 
+     * @param fragment the {@code Calendar} field part of calendar to calculate 
      * @return number of milliseconds within the fragment of date
      * @throws IllegalArgumentException if the date is <code>null</code> or 
      * fragment is not supported
@@ -1504,7 +1475,7 @@ public class DateUtils {
      * </p>
      * 
      * @param calendar the calendar to work with, not null
-     * @param fragment the Calendar field part of calendar to calculate 
+     * @param fragment the {@code Calendar} field part of calendar to calculate 
      * @return number of seconds within the fragment of date
      * @throws IllegalArgumentException if the date is <code>null</code> or 
      * fragment is not supported
@@ -1544,7 +1515,7 @@ public class DateUtils {
      * </p>
      * 
      * @param calendar the calendar to work with, not null
-     * @param fragment the Calendar field part of calendar to calculate 
+     * @param fragment the {@code Calendar} field part of calendar to calculate 
      * @return number of minutes within the fragment of date
      * @throws IllegalArgumentException if the date is <code>null</code> or 
      * fragment is not supported
@@ -1584,7 +1555,7 @@ public class DateUtils {
      * </p>
      *  
      * @param calendar the calendar to work with, not null
-     * @param fragment the Calendar field part of calendar to calculate 
+     * @param fragment the {@code Calendar} field part of calendar to calculate 
      * @return number of hours within the fragment of date
      * @throws IllegalArgumentException if the date is <code>null</code> or 
      * fragment is not supported
@@ -1626,7 +1597,7 @@ public class DateUtils {
      * </p>
      * 
      * @param calendar the calendar to work with, not null
-     * @param fragment the Calendar field part of calendar to calculate 
+     * @param fragment the {@code Calendar} field part of calendar to calculate 
      * @return number of days within the fragment of date
      * @throws IllegalArgumentException if the date is <code>null</code> or 
      * fragment is not supported
@@ -1641,7 +1612,7 @@ public class DateUtils {
      * 
      * @param date the date to work with, not null
      * @param fragment the Calendar field part of date to calculate 
-     * @param unit Calendar field defining the unit
+     * @param unit the {@code Calendar} field defining the unit
      * @return number of units within the fragment of the date
      * @throws IllegalArgumentException if the date is <code>null</code> or 
      * fragment is not supported
@@ -1661,7 +1632,7 @@ public class DateUtils {
      * 
      * @param calendar the calendar to work with, not null
      * @param fragment the Calendar field part of calendar to calculate 
-     * @param unit Calendar field defining the unit
+     * @param unit the {@code Calendar} field defining the unit
      * @return number of units within the fragment of the calendar
      * @throws IllegalArgumentException if the date is <code>null</code> or 
      * fragment is not supported
@@ -1715,7 +1686,7 @@ public class DateUtils {
      * 
      * @param cal1 the first calendar, not <code>null</code>
      * @param cal2 the second calendar, not <code>null</code>
-     * @param field the field from <code>Calendar</code>
+     * @param field the field from {@code Calendar}
      * @return <code>true</code> if equal; otherwise <code>false</code>
      * @throws IllegalArgumentException if any argument is <code>null</code>
      * @see #truncate(Calendar, int)
@@ -1732,7 +1703,7 @@ public class DateUtils {
      * 
      * @param date1 the first date, not <code>null</code>
      * @param date2 the second date, not <code>null</code>
-     * @param field the field from <code>Calendar</code>
+     * @param field the field from {@code Calendar}
      * @return <code>true</code> if equal; otherwise <code>false</code>
      * @throws IllegalArgumentException if any argument is <code>null</code>
      * @see #truncate(Date, int)
@@ -1749,7 +1720,7 @@ public class DateUtils {
      * 
      * @param cal1 the first calendar, not <code>null</code>
      * @param cal2 the second calendar, not <code>null</code>
-     * @param field the field from <code>Calendar</code>
+     * @param field the field from {@code Calendar}
      * @return a negative integer, zero, or a positive integer as the first 
      * calendar is less than, equal to, or greater than the second.
      * @throws IllegalArgumentException if any argument is <code>null</code>
@@ -1782,13 +1753,14 @@ public class DateUtils {
         Date truncatedDate2 = truncate(date2, field);
         return truncatedDate1.compareTo(truncatedDate2);
     }
-    
+
     /**
-     * Returns the number of millis of a datefield, if this is a constant value
+     * Returns the number of milliseconds of a {@code Calendar} field, if this is a constant
value.
+     * This handles millisecond, second, minute, hour and day (even though days can very
in length).
      * 
-     * @param unit A Calendar field which is a valid unit for a fragment
-     * @return number of millis
-     * @throws IllegalArgumentException if date can't be represented in millisenconds
+     * @param unit  a {@code Calendar} field constant which is a valid unit for a fragment
+     * @return the number of milliseconds in the field
+     * @throws IllegalArgumentException if date can't be represented in milliseconds
      * @since 2.4 
      */
     private static long getMillisPerUnit(int unit) {
@@ -1815,6 +1787,7 @@ public class DateUtils {
         return result;
     }
 
+    //-----------------------------------------------------------------------
     /**
      * <p>Date iterator.</p>
      */
@@ -1867,5 +1840,5 @@ public class DateUtils {
             throw new UnsupportedOperationException();
         }
     }
-    
+
 }



Mime
View raw message