Author: scolebourne Date: Sun Apr 16 13:55:25 2006 New Revision: 394555 URL: http://svn.apache.org/viewcvs?rev=394555&view=rev Log: Javadoc to explain what iterator methods actually do bug 33609
Modified: jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DateUtils.java Modified: jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DateUtils.java URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DateUtils.java?rev=394555&r1=394554&r2=394555&view=diff ============================================================================== --- jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DateUtils.java (original) +++ jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DateUtils.java Sun Apr 16 13:55:25 2006 @@ -697,22 +697,28 @@ //----------------------------------------------------------------------- /** - * <p>This constructs an <code>Iterator</code> that will - * start and stop over a date range based on the focused - * date and the range style.</p> + * <p>This constructs an <code>Iterator</code> over each day in a date + * range defined by a focus date and range style.</p> * * <p>For instance, passing Thursday, July 4, 2002 and a - * <code>RANGE_MONTH_SUNDAY</code> will return an - * <code>Iterator</code> that starts with Sunday, June 30, - * 2002 and ends with Saturday, August 3, 2002. - * - * @param focus the date to work with - * @param rangeStyle the style constant to use. Must be one of the range - * styles listed for the [EMAIL PROTECTED] #iterator(Calendar, int)} method. + * <code>RANGE_MONTH_SUNDAY</code> will return an <code>Iterator</code> + * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3, + * 2002, returning a Calendar instance for each intermediate day.</p> * - * @return the date iterator - * @throws IllegalArgumentException if the date is <code>null</code> or if - * the rangeStyle is not + * <p>This method provides an iterator that returns Calendar objects. + * The days are progressed using [EMAIL PROTECTED] Calendar#add(int, int)}.</p> + * + * @param focus the date to work with, not null + * @param rangeStyle the style constant to use. Must be one of + * [EMAIL PROTECTED] DateUtils#RANGE_MONTH_SUNDAY}, + * [EMAIL PROTECTED] DateUtils#RANGE_MONTH_MONDAY}, + * [EMAIL PROTECTED] DateUtils#RANGE_WEEK_SUNDAY}, + * [EMAIL PROTECTED] DateUtils#RANGE_WEEK_MONDAY}, + * [EMAIL PROTECTED] DateUtils#RANGE_WEEK_RELATIVE}, + * [EMAIL PROTECTED] DateUtils#RANGE_WEEK_CENTER} + * @return the date iterator, which always returns Calendar instances + * @throws IllegalArgumentException if the date is <code>null</code> + * @throws IllegalArgumentException if the rangeStyle is invalid */ public static Iterator iterator(Date focus, int rangeStyle) { if (focus == null) { @@ -724,15 +730,17 @@ } /** - * <p>This constructs an <code>Iterator</code> that will - * start and stop over a date range based on the focused - * date and the range style.</p> + * <p>This constructs an <code>Iterator</code> over each day in a date + * range defined by a focus date and range style.</p> * * <p>For instance, passing Thursday, July 4, 2002 and a - * <code>RANGE_MONTH_SUNDAY</code> will return an - * <code>Iterator</code> that starts with Sunday, June 30, - * 2002 and ends with Saturday, August 3, 2002. - * + * <code>RANGE_MONTH_SUNDAY</code> will return an <code>Iterator</code> + * that starts with Sunday, June 30, 2002 and ends with Saturday, August 3, + * 2002, returning a Calendar instance for each intermediate day.</p> + * + * <p>This method provides an iterator that returns Calendar objects. + * The days are progressed using [EMAIL PROTECTED] Calendar#add(int, int)}.</p> + * * @param focus the date to work with * @param rangeStyle the style constant to use. Must be one of * [EMAIL PROTECTED] DateUtils#RANGE_MONTH_SUNDAY}, @@ -743,6 +751,7 @@ * [EMAIL PROTECTED] DateUtils#RANGE_WEEK_CENTER} * @return the date iterator * @throws IllegalArgumentException if the date is <code>null</code> + * @throws IllegalArgumentException if the rangeStyle is invalid */ public static Iterator iterator(Calendar focus, int rangeStyle) { if (focus == null) { @@ -817,15 +826,14 @@ } /** - * <p>This constructs an <code>Iterator</code> that will - * start and stop over a date range based on the focused - * date and the range style.</p> + * <p>This constructs an <code>Iterator</code> over each day in a date + * range defined by a focus date and range style.</p> * * <p>For instance, passing Thursday, July 4, 2002 and a - * <code>RANGE_MONTH_SUNDAY</code> will return an - * <code>Iterator</code> that starts with Sunday, June 30, - * 2002 and ends with Saturday, August 3, 2002.</p> - * + * <code>RANGE_MONTH_SUNDAY</code> will return an <code>Iterator</code> + * 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 rangeStyle the style constant to use. Must be one of the range --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]