Javadoc and stylistic changes

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

src/java/org/apache/commons/collections/iterators/ListIteratorWrapper.java

@@ -21,9 +21,15 @@ import java.util.ListIterator;
 import java.util.NoSuchElementException;
 
 /**
- * As the wrapped Iterator is traversed, ListIteratorWrapper
+ * Converts an iterator into a list iterator by caching the returned entries.
- * builds a LinkedList of its values, permitting all required
+ * <p>
- * operations of ListIterator.
+ * The <code>ListIterator</code> interface has additional useful methods
+ * for navigation - <code>previous()</code> and the index methods.
+ * This class allows a regular <code>Iterator</code> to behave as a
+ * <code>ListIterator</code>. It achieves this by building a list internally
+ * of as the underlying iterator is traversed.
+ * <p>
+ * The optional operations of <code>ListIterator</code> are not supported.
  *
  * @since Commons Collections 2.1
  * @version $Revision$ $Date$
@@ -33,22 +39,22 @@ import java.util.NoSuchElementException;
  */
 public class ListIteratorWrapper implements ListIterator {
 
-    /** Holds value of property "iterator" */
+    /** Message used when remove, set or add are called. */
-    private final Iterator iterator;
-    private final LinkedList list = new LinkedList();
-    
-    // position of this iterator
-    private int currentIndex = 0;
-    // position of the wrapped iterator
-    // this Iterator should only be used to populate the list
-    private int wrappedIteratorIndex = 0;
-
     private static final String UNSUPPORTED_OPERATION_MESSAGE =
         "ListIteratorWrapper does not support optional operations of ListIterator.";
 
+    /** The underlying iterator being decorated. */
+    private final Iterator iterator;
+    /** The list being used to cache the iterator. */
+    private final LinkedList list = new LinkedList();
+
+    /** The current index of this iterator. */
+    private int currentIndex = 0;
+    /** The current index of the wrapped iterator. */
+    private int wrappedIteratorIndex = 0;
+
     // Constructor
     //-------------------------------------------------------------------------
-
     /**
      * Constructs a new <code>ListIteratorWrapper</code> that will wrap
      * the given iterator.
@@ -66,18 +72,16 @@ public class ListIteratorWrapper implements ListIterator {
 
     // ListIterator interface
     //-------------------------------------------------------------------------
-
     /**
      * Throws {@link UnsupportedOperationException}.
      *
-     *  @param o  ignored
+     * @param obj  the object to add, ignored
      * @throws UnsupportedOperationException always
      */
-    public void add(Object o) throws UnsupportedOperationException {
+    public void add(Object obj) throws UnsupportedOperationException {
         throw new UnsupportedOperationException(UNSUPPORTED_OPERATION_MESSAGE);
     }
 
-
     /**
      * Returns true if there are more elements in the iterator.
      *
@@ -87,7 +91,6 @@ public class ListIteratorWrapper implements ListIterator {
         if (currentIndex == wrappedIteratorIndex) {
             return iterator.hasNext();
         }
-
         return true;
     }
 
@@ -100,7 +103,6 @@ public class ListIteratorWrapper implements ListIterator {
         if (currentIndex == 0) {
             return false;
         }
-
         return true;
     }
 
@@ -142,7 +144,6 @@ public class ListIteratorWrapper implements ListIterator {
         if (currentIndex == 0) {
             throw new NoSuchElementException();
         }
-
         --currentIndex;
         return list.get(currentIndex);    
     }
@@ -168,12 +169,11 @@ public class ListIteratorWrapper implements ListIterator {
     /**
      * Throws {@link UnsupportedOperationException}.
      *
-     *  @param o  ignored
+     * @param obj  the object to set, ignored
      * @throws UnsupportedOperationException always
      */
-    public void set(Object o) throws UnsupportedOperationException {
+    public void set(Object obj) throws UnsupportedOperationException {
         throw new UnsupportedOperationException(UNSUPPORTED_OPERATION_MESSAGE);
     }
 
 }
-