Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Jakarta Commons Developers List" <commons-dev@jakarta.apache.org>
Message-ID: <20060416205527.97248.qmail@minotaur.apache.org>
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r394555 -
 /jakarta/commons/proper/lang/trunk/src/java/org/apache/commons/lang/time/DateUtils.java
Date: Sun, 16 Apr 2006 20:55:26 -0000
To: commons-cvs@jakarta.apache.org
From: scolebourne@apache.org

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 {@link #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 {@link 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
+     * {@link DateUtils#RANGE_MONTH_SUNDAY}, 
+     * {@link DateUtils#RANGE_MONTH_MONDAY},
+     * {@link DateUtils#RANGE_WEEK_SUNDAY},
+     * {@link DateUtils#RANGE_WEEK_MONDAY},
+     * {@link DateUtils#RANGE_WEEK_RELATIVE},
+     * {@link 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 {@link Calendar#add(int, int)}.</p>
+     *
      * @param focus  the date to work with
      * @param rangeStyle  the style constant to use. Must be one of
      * {@link DateUtils#RANGE_MONTH_SUNDAY}, 
@@ -743,6 +751,7 @@
      * {@link 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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org