add javadocs to Int[List]Iterator

fix typo in IntList javadocs


git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130932 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/collections/primitives/IntIterator.java

@@ -1,7 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/IntIterator.java,v 1.1 2003/01/04 15:00:57 rwaldhoff Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/IntIterator.java,v 1.2 2003/01/10 19:24:10 rwaldhoff Exp $
- * $Revision: 1.1 $
- * $Date: 2003/01/04 15:00:57 $
  *
  * ====================================================================
  *
@@ -23,11 +21,11 @@
  *    distribution.
  *
  * 3. The end-user documentation included with the redistribution, if
- *    any, must include the following acknowlegement:
+ *    any, must include the following acknowledgment:
  *       "This product includes software developed by the
  *        Apache Software Foundation (http://www.apache.org/)."
- *    Alternately, this acknowlegement may appear in the software itself,
+ *    Alternately, this acknowledgment may appear in the software itself,
- *    if and wherever such third-party acknowlegements normally appear.
+ *    if and wherever such third-party acknowledgments normally appear.
  *
  * 4. The names "The Jakarta Project", "Commons", and "Apache Software
  *    Foundation" must not be used to endorse or promote products derived
@@ -62,20 +60,31 @@
 package org.apache.commons.collections.primitives;
 
 /**
- * A {@link java.util.Iterator iterator} over int values.
+ * An iterator over <code>int</code> values.
+ *
+ * @see org.apache.commons.collections.primitives.adapters.IntIteratorIterator
+ * @see org.apache.commons.collections.primitives.adapters.IteratorIntIterator
+ *
+ * @since Commons Collections 2.2
+ * @version $Revision: 1.2 $ $Date: 2003/01/10 19:24:10 $
  * 
- * @version $Revision: 1.1 $ $Date: 2003/01/04 15:00:57 $
  * @author Rodney Waldhoff 
  */
 public interface IntIterator {
     /** 
-     * Returns <code>true</code> iff 
+     * Returns <code>true</code> iff I have more elements. 
-     * I have more elements. 
+     * (In other words, returns <code>true</code> iff 
+     * a call to {@link #next next} will return an element
+     * rather than throwing an exception.
+     * 
+     * @return <code>true</code> iff I have more elements
      */
     boolean hasNext();
     
     /** 
      * Returns the next element in me.
+     * 
+     * @return the next element in me
      * @throws NoSuchElementException if there is no next element
      */          
     int next();
@@ -84,9 +93,10 @@ public interface IntIterator {
      * Removes from my underlying collection the last 
      * element {@link #next returned} by me 
      * (optional operation). 
-     * @throws UnsupportedOperationException if remove is not supported
+     * 
+     * @throws UnsupportedOperationException if this operation is not supported
      * @throws IllegalStateException if {@link #next} has not yet been 
-     *         called, or {@link #remove} has already been called after 
+     *         called, or {@link #remove} has already been called since 
      *         the last call to {@link #next}.
      */          
     void remove();

src/java/org/apache/commons/collections/primitives/IntList.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/IntList.java,v 1.6 2003/01/10 18:52:37 rwaldhoff Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/IntList.java,v 1.7 2003/01/10 19:24:10 rwaldhoff Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -67,7 +67,7 @@ package org.apache.commons.collections.primitives;
  * @see org.apache.commons.collections.primitives.adapters.ListIntList
  *
  * @since Commons Collections 2.2
- * @version $Revision: 1.6 $ $Date: 2003/01/10 18:52:37 $
+ * @version $Revision: 1.7 $ $Date: 2003/01/10 19:24:10 $
  * 
  * @author Rodney Waldhoff 
  */
@@ -83,7 +83,7 @@ public interface IntList extends IntCollection {
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
-     * @throws IllegalArgumentException is some aspect of the specified element 
+     * @throws IllegalArgumentException if some aspect of the specified element 
      *         prevents it from being added to me
      * @throws IndexOutOfBoundsException if the specified index is out of range
      */

src/java/org/apache/commons/collections/primitives/IntListIterator.java

@@ -1,7 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/IntListIterator.java,v 1.3 2003/01/10 18:52:37 rwaldhoff Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/IntListIterator.java,v 1.4 2003/01/10 19:24:10 rwaldhoff Exp $
- * $Revision: 1.3 $
- * $Date: 2003/01/10 18:52:37 $
  *
  * ====================================================================
  *
@@ -62,19 +60,129 @@
 package org.apache.commons.collections.primitives;
 
 /**
- * A {@link java.util.ListIterator list iterator} over int values.
+ * A list iterator over <code>int</code> values.
+ *
+ * @see org.apache.commons.collections.primitives.adapters.IntListIteratorListIterator
+ * @see org.apache.commons.collections.primitives.adapters.ListIteratorIntListIterator
+ *
+ * @since Commons Collections 2.2
+ * @version $Revision: 1.4 $ $Date: 2003/01/10 19:24:10 $
  * 
- * @version $Revision: 1.3 $ $Date: 2003/01/10 18:52:37 $
  * @author Rodney Waldhoff 
  */
 public interface IntListIterator extends IntIterator {
+    /**
+     * Inserts the specified element into my underlying collection
+     * (optional operation).
+     * The element is inserted immediately before the next element 
+     * that would have been returned by {@link #next}, if any,
+     * and immediately after the next element that would have been 
+     * returned by {@link #previous}, if any.
+     * <p/>
+     * The new element is inserted immediately before the implied
+     * cursor. A subsequent call to {@link #previous} will return
+     * the added element, a subsequent call to {@link #next} will
+     * be unaffected.  This call increases by one the value that
+     * would be returned by a call to {@link #nextIndex} or 
+     * {@link #previousIndex}.
+     * 
+     * @param element the value to be inserted
+     * 
+     * @throws UnsupportedOperationException when this operation is not 
+     *         supported
+     * @throws IllegalArgumentException if some aspect of the specified element 
+     *         prevents it from being added
+     */
     void add(int element);
+
+    /** 
+     * Returns <code>true</code> iff I have more elements
+     * when traversed in the forward direction. 
+     * (In other words, returns <code>true</code> iff 
+     * a call to {@link #next} will return an element
+     * rather than throwing an exception.
+     * 
+     * @return <code>true</code> iff I have more elements when 
+     *         traversed in the forward direction
+     */
     boolean hasNext();
+    
+    /** 
+     * Returns <code>true</code> iff I have more elements
+     * when traversed in the reverse direction. 
+     * (In other words, returns <code>true</code> iff 
+     * a call to {@link #previous} will return an element
+     * rather than throwing an exception.
+     * 
+     * @return <code>true</code> iff I have more elements when 
+     *         traversed in the reverse direction
+     */
     boolean hasPrevious();
+
+    /** 
+     * Returns the next element in me when traversed in the
+     * forward direction.
+     * 
+     * @return the next element in me
+     * @throws NoSuchElementException if there is no next element
+     */          
     int next();
+    
+    /** 
+     * Returns the index of the element that would be returned
+     * by a subsequent call to {@link #next}, or the number 
+     * of elements in my iteration if I have no next element.
+     * 
+     * @return the index of the next element in me
+     */          
     int nextIndex();
+
+    /** 
+     * Returns the next element in me when traversed in the
+     * reverse direction.
+     * 
+     * @return the previous element in me
+     * @throws NoSuchElementException if there is no previous element
+     */          
     int previous();
+
+    /** 
+     * Returns the index of the element that would be returned
+     * by a subsequent call to {@link #previous}, or 
+     * <code>-1</code> if I have no previous element.
+     * 
+     * @return the index of the previous element in me
+     */          
     int previousIndex();
+
+    /** 
+     * Removes from my underlying collection the last 
+     * element returned by {@link #next} or {@link #previous}
+     * (optional operation). 
+     * 
+     * @throws UnsupportedOperationException if this operation is not 
+     *         supported
+     * @throws IllegalStateException if neither {@link #next} nor
+     *         {@link #previous} has yet been called, or 
+     *         {@link #remove} or {@link #add} has already been called since 
+     *         the last call to {@link #next} or {@link #previous}.
+     */          
     void remove();
+
+    /** 
+     * Replaces in my underlying collection the last 
+     * element returned by {@link #next} or {@link #previous}
+     * with the specified value (optional operation). 
+     * 
+     * @param element the value to replace the last returned element with
+     * @throws UnsupportedOperationException if this operation is not 
+     *         supported
+     * @throws IllegalStateException if neither {@link #next} nor
+     *         {@link #previous} has yet been called, or 
+     *         {@link #remove} or {@link #add} has already been called since 
+     *         the last call to {@link #next} or {@link #previous}.
+     * @throws IllegalArgumentException if some aspect of the specified element 
+     *         prevents it from being added
+     */          
     void set(int element);
 }