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]
