From e648a45b617b209fdb42b06720ad3bae397de6ca Mon Sep 17 00:00:00 2001 From: Rodney Waldhoff Date: Fri, 10 Jan 2003 19:24:10 +0000 Subject: [PATCH] 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 --- .../collections/primitives/IntIterator.java | 34 +++-- .../collections/primitives/IntList.java | 6 +- .../primitives/IntListIterator.java | 118 +++++++++++++++++- 3 files changed, 138 insertions(+), 20 deletions(-) diff --git a/src/java/org/apache/commons/collections/primitives/IntIterator.java b/src/java/org/apache/commons/collections/primitives/IntIterator.java index 4e3b21bf5..4e12d4c20 100644 --- a/src/java/org/apache/commons/collections/primitives/IntIterator.java +++ b/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 $ - * $Revision: 1.1 $ - * $Date: 2003/01/04 15:00:57 $ + * $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 $ * * ==================================================================== * @@ -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, - * if and wherever such third-party acknowlegements normally appear. + * Alternately, this acknowledgment may appear in the software itself, + * 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 int values. * - * @version $Revision: 1.1 $ $Date: 2003/01/04 15:00:57 $ + * @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 $ + * * @author Rodney Waldhoff */ public interface IntIterator { /** - * Returns true iff - * I have more elements. + * Returns true iff I have more elements. + * (In other words, returns true iff + * a call to {@link #next next} will return an element + * rather than throwing an exception. + * + * @return true 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(); diff --git a/src/java/org/apache/commons/collections/primitives/IntList.java b/src/java/org/apache/commons/collections/primitives/IntList.java index 11a6c53a2..546791354 100644 --- a/src/java/org/apache/commons/collections/primitives/IntList.java +++ b/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 */ diff --git a/src/java/org/apache/commons/collections/primitives/IntListIterator.java b/src/java/org/apache/commons/collections/primitives/IntListIterator.java index 4ac2c4dca..00eac3cdf 100644 --- a/src/java/org/apache/commons/collections/primitives/IntListIterator.java +++ b/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 $ - * $Revision: 1.3 $ - * $Date: 2003/01/10 18:52:37 $ + * $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 $ * * ==================================================================== * @@ -62,19 +60,129 @@ package org.apache.commons.collections.primitives; /** - * A {@link java.util.ListIterator list iterator} over int values. + * A list iterator over int values. * - * @version $Revision: 1.3 $ $Date: 2003/01/10 18:52:37 $ + * @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 $ + * * @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. + *

+ * 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 true iff I have more elements + * when traversed in the forward direction. + * (In other words, returns true iff + * a call to {@link #next} will return an element + * rather than throwing an exception. + * + * @return true iff I have more elements when + * traversed in the forward direction + */ boolean hasNext(); + + /** + * Returns true iff I have more elements + * when traversed in the reverse direction. + * (In other words, returns true iff + * a call to {@link #previous} will return an element + * rather than throwing an exception. + * + * @return true 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 + * -1 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); }