From 8ab071ff5dac65b2587b20940490a3bde4d132d7 Mon Sep 17 00:00:00 2001
From: pjack <pjack@apache.org>
Date: Thu, 15 Aug 2002 20:04:31 +0000
Subject: [PATCH] Documented (almost) all public/protected members. PR:
 Obtained from: Submitted by: Reviewed by:

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130775 13f79535-47bb-0310-9956-ffa450edef68
---
 .../commons/collections/ArrayIterator.java    |  26 +-
 .../commons/collections/ArrayStack.java       |  15 +-
 .../apache/commons/collections/BeanMap.java   | 230 ++++++++++++-
 .../commons/collections/BinaryHeap.java       |  64 +++-
 .../collections/BufferUnderflowException.java |  12 +-
 .../commons/collections/BufferUtils.java      |  18 +-
 .../collections/CollatingIterator.java        |  63 +++-
 .../commons/collections/CollectionUtils.java  |  14 +-
 .../commons/collections/DefaultMapBag.java    |  96 +++++-
 .../commons/collections/DefaultMapEntry.java  |  35 +-
 .../collections/EnumerationIterator.java      |  53 ++-
 .../commons/collections/FactoryUtils.java     |  11 +-
 .../commons/collections/FastArrayList.java    |  19 +-
 .../commons/collections/FastHashMap.java      |  18 +-
 .../commons/collections/FastTreeMap.java      |  19 +-
 .../commons/collections/FilterIterator.java   |  41 ++-
 .../collections/FilterListIterator.java       |  34 +-
 .../apache/commons/collections/HashBag.java   |  10 +-
 .../collections/IteratorEnumeration.java      |  43 ++-
 .../collections/ListIteratorWrapper.java      |  64 +++-
 .../apache/commons/collections/ListUtils.java |  57 +++-
 .../apache/commons/collections/MapUtils.java  | 316 +++++++++++++++++-
 .../apache/commons/collections/Predicate.java |  11 +-
 .../commons/collections/PredicateUtils.java   |  10 +-
 .../commons/collections/ProxyIterator.java    |  36 +-
 .../collections/ProxyListIterator.java        |  64 +++-
 .../apache/commons/collections/ProxyMap.java  |  48 ++-
 .../commons/collections/SequencedHashMap.java |  73 +++-
 .../collections/SingletonIterator.java        |  30 +-
 .../commons/collections/StaticBucketMap.java  |  48 +--
 .../SynchronizedPriorityQueue.java            |  21 +-
 .../collections/TransformIterator.java        |  33 +-
 .../apache/commons/collections/TreeBag.java   |  10 +-
 .../collections/UniqueFilterIterator.java     |  13 +-
 34 files changed, 1473 insertions(+), 182 deletions(-)

diff --git a/src/java/org/apache/commons/collections/ArrayIterator.java b/src/java/org/apache/commons/collections/ArrayIterator.java
index 89e72ad95..dd979d67e 100644
--- a/src/java/org/apache/commons/collections/ArrayIterator.java
+++ b/src/java/org/apache/commons/collections/ArrayIterator.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/ArrayIterator.java,v 1.14 2002/06/20 02:51:18 bayard Exp $
- * $Revision: 1.14 $
- * $Date: 2002/06/20 02:51:18 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/ArrayIterator.java,v 1.15 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.15 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -70,7 +70,7 @@ import java.util.NoSuchElementException;
   * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
   * @author Mauricio S. Moura
   * @author <a href="mailto:mas@apache.org">Michael A. Smith</a>
-  * @version $Revision: 1.14 $
+  * @version $Revision: 1.15 $
   */
 public class ArrayIterator implements Iterator {
     
@@ -166,10 +166,23 @@ public class ArrayIterator implements Iterator {
 
     // Iterator interface
     //-------------------------------------------------------------------------
+
+    /**
+     *  Returns true if there are more elements to return from the array.
+     *
+     *  @return true if there is a next element to return
+     */
     public boolean hasNext() {
         return index < length;
     }
 
+    /**
+     *  Returns the next element in the array.
+     *
+     *  @return the next element in the array
+     *  @throws NoSuchElementException if all the elements in the array
+     *    have already been returned
+     */
     public Object next() {
         if(!hasNext()) {
             throw new NoSuchElementException();
@@ -177,6 +190,11 @@ public class ArrayIterator implements Iterator {
         return Array.get( array, index++ );
     }
 
+    /**
+     *  Throws {@link UnsupportedOperationException}.
+     *
+     *  @throws UnsupportedOperationException always
+     */
     public void remove() {
         throw new UnsupportedOperationException( "remove() method is not supported" );
     }
diff --git a/src/java/org/apache/commons/collections/ArrayStack.java b/src/java/org/apache/commons/collections/ArrayStack.java
index ddfa97c27..6dc79df69 100644
--- a/src/java/org/apache/commons/collections/ArrayStack.java
+++ b/src/java/org/apache/commons/collections/ArrayStack.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/ArrayStack.java,v 1.7 2002/07/03 02:16:48 mas Exp $
- * $Revision: 1.7 $
- * $Date: 2002/07/03 02:16:48 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/ArrayStack.java,v 1.8 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.8 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -82,7 +82,7 @@ import java.util.Stack; // only used in javadoc comments, javadoc won't find it
  *
  * @since 1.0
  * @author Craig R. McClanahan
- * @version $Revision: 1.7 $ $Date: 2002/07/03 02:16:48 $
+ * @version $Revision: 1.8 $ $Date: 2002/08/15 20:04:31 $
  * @see java.util.Stack
  */
 
@@ -92,6 +92,13 @@ public class ArrayStack extends ArrayList implements Buffer {
     final private static long serialVersionUID = 2130079159931574599L;
 //, local class serialVersionUID = -3491241305852305742
 
+    /**
+     *  Constructs a new empty <Code>ArrayStack</Code>.
+     */
+    public ArrayStack() {
+        super();
+    }
+
     // --------------------------------------------------------- Public Methods
 
 
diff --git a/src/java/org/apache/commons/collections/BeanMap.java b/src/java/org/apache/commons/collections/BeanMap.java
index 3dfcf7b08..8c77cc659 100644
--- a/src/java/org/apache/commons/collections/BeanMap.java
+++ b/src/java/org/apache/commons/collections/BeanMap.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BeanMap.java,v 1.12 2002/08/10 02:05:20 pjack Exp $
- * $Revision: 1.12 $
- * $Date: 2002/08/10 02:05:20 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BeanMap.java,v 1.13 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.13 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -96,7 +96,15 @@ public class BeanMap extends AbstractMap implements Cloneable {
     private transient HashMap writeMethods = new HashMap();
     private transient HashMap types = new HashMap();
 
+    /**
+     *  An empty array.  Used to invoke accessors via reflection.
+     */
     public static final Object[] NULL_ARGUMENTS = {};
+
+    /**
+     *  Maps primitive Class types to transformers.  The transformer
+     *  transform strings into the appropriate primitive wrapper.
+     */
     public static HashMap defaultTransformers = new HashMap();
     
     static {
@@ -169,9 +177,20 @@ public class BeanMap extends AbstractMap implements Cloneable {
     
     // Constructors
     //-------------------------------------------------------------------------
+
+    /**
+     *  Constructs a new empty <Code>BeanMap</Code>.
+     */
     public BeanMap() {
     }
 
+    /**
+     *  Constructs a new <Code>BeanMap</Code> that operates on the 
+     *  specified bean.  If the given bean is <Code>null</COde>, then
+     *  this map will be empty.
+     *
+     *  @param bean  the bean for this map to operate on
+     */
     public BeanMap(Object bean) {
         this.bean = bean;
         initialise();
@@ -291,16 +310,46 @@ public class BeanMap extends AbstractMap implements Cloneable {
         }
     }
 
+    /**
+     *  Returns true if the bean defines a property with the given name.
+     *  The given name must be a <Code>String</Code>; if not, this method
+     *  returns false.  This method will also return false if the bean
+     *  does not define a property with that name.
+     *
+     *  @param name  the name of the property to check
+     *  @return false if the given name is null or is not a <Code>String</Code>;
+     *    false if the bean does not define a property with that name; or
+     *    true if the bean does define a property with that name
+     */
     public boolean containsKey(Object name) {
         Method method = getReadMethod( name );
         return method != null;
     }
 
+    /**
+     *  Returns true if the bean defines a property whose current value is
+     *  the given object.
+     *
+     *  @param value  the value to check
+     *  @return false  true if the bean has at least one property whose 
+     *    current value is that object, false otherwise
+     */
     public boolean containsValue(Object value) {
         // use default implementation
         return super.containsValue( value );
     }
 
+    /**
+     *  Returns the value of the bean's property with the given name.
+     *  The given name must be a {@link String} and must not be 
+     *  null; otherwise, this method returns <Code>null</Code>.
+     *  If the bean defines a property with the given name, the value of
+     *  that property is returned.  Otherwise, <Code>null</Code> is 
+     *  returned.
+     *
+     *  @param name  the name of the property whose value to return
+     *  @return  the value of the property with that name
+     */
     public Object get(Object name) {
         if ( bean != null ) {
             Method method = getReadMethod( name );
@@ -325,6 +374,17 @@ public class BeanMap extends AbstractMap implements Cloneable {
         return null;
     }
 
+    /**
+     *  Sets the bean property with the given name to the given value.
+     *
+     *  @param name  the name of the property to set
+     *  @param value  the value to set that property to
+     *  @return  the previous value of that property
+     *  @throws IllegalArgumentException  if the given name is null;
+     *    if the given name is not a {@link String}; if the bean doesn't
+     *    define a property with that name; or if the bean property with
+     *    that name is read-only
+     */
     public Object put(Object name, Object value) throws IllegalArgumentException, ClassCastException {
         if ( bean != null ) {
             Object oldValue = get( name );
@@ -352,6 +412,11 @@ public class BeanMap extends AbstractMap implements Cloneable {
         return null;
     }
                     
+    /**
+     *  Returns the number of properties defined by the bean.
+     *
+     *  @return  the number of properties defined by the bean
+     */
     public int size() {
         return readMethods.size();
     }
@@ -360,7 +425,7 @@ public class BeanMap extends AbstractMap implements Cloneable {
     /**
      * Get the keys for this BeanMap.
      * 
-     * @return BeanMap keys.  The Set returned bu this method is not
+     * @return BeanMap keys.  The Set returned by this method is not
      *         modifiable.
      */
     public Set keySet() {
@@ -420,15 +485,32 @@ public class BeanMap extends AbstractMap implements Cloneable {
 
     // Helper methods
     //-------------------------------------------------------------------------
-    
+
+    /**
+     * Returns the type of the property with the given name.
+     *
+     * @param name  the name of the property
+     * @return  the type of the property, or <Code>null</Code> if no such
+     *   property exists
+     */
     public Class getType(String name) {
         return (Class) types.get( name );
     }
 
+    /**
+     *  Convenience method for getting an iterator over the keys.
+     *
+     *  @return an iterator over the keys
+     */
     public Iterator keyIterator() {
         return readMethods.keySet().iterator();
     }
 
+    /**
+     *  Convenience method for getting an iterator over the values.
+     *
+     *  @return an iterator over the values
+     */
     public Iterator valueIterator() {
         final Iterator iter = keyIterator();
         return new Iterator() {            
@@ -445,6 +527,11 @@ public class BeanMap extends AbstractMap implements Cloneable {
         };
     }
 
+    /**
+     *  Convenience method for getting an iterator over the entries.
+     *
+     *  @return an iterator over the entries
+     */
     public Iterator entryIterator() {
         final Iterator iter = keyIterator();
         return new Iterator() {            
@@ -465,10 +552,23 @@ public class BeanMap extends AbstractMap implements Cloneable {
 
     // Properties
     //-------------------------------------------------------------------------
+
+    /**
+     *  Returns the bean currently being operated on.  The return value may
+     *  be null if this map is empty.
+     *
+     *  @return the bean being operated on by this map
+     */
     public Object getBean() {
         return bean;
     }
 
+    /**
+     *  Sets the bean to be operated on by this map.  The given value may
+     *  be null, in which case this map will be empty.
+     *
+     *  @param newBean  the new bean to operate on
+     */
     public void setBean( Object newBean ) {
         bean = newBean;
         reinitialise();
@@ -478,14 +578,34 @@ public class BeanMap extends AbstractMap implements Cloneable {
     // Implementation methods
     //-------------------------------------------------------------------------
 
+    /**
+     *  Returns the accessor for the property with the given name.
+     *
+     *  @param name  the name of the property 
+     *  @return null if the name is null; null if the name is not a 
+     *  {@link String}; null if no such property exists; or the accessor
+     *   method for that property
+     */
     protected Method getReadMethod( Object name ) {
         return (Method) readMethods.get( name );
     }
 
+    /**
+     *  Returns the mutator for the property with the given name.
+     *
+     *  @param name  the name of the 
+     *  @return null if the name is null; null if the name is not a 
+     *  {@link String}; null if no such property exists; null if the 
+     *  property is read-only; or the mutator method for that property
+     */
     protected Method getWriteMethod( Object name ) {
         return (Method) writeMethods.get( name );
     }
 
+    /**
+     *  Reinitializes this bean.  Called during {@link #setBean(Object)}.
+     *  Does introspection to find properties.
+     */
     protected void reinitialise() {
         readMethods.clear();
         writeMethods.clear();
@@ -526,19 +646,45 @@ public class BeanMap extends AbstractMap implements Cloneable {
         }
     }
 
+    /**
+     *  Called during a successful {@link #put(Object,Object)} operation.
+     *  Default implementation does nothing.  Override to be notified of
+     *  property changes in the bean caused by this map.
+     *
+     *  @param key  the name of the property that changed
+     *  @param oldValue  the old value for that property
+     *  @param newValue  the new value for that property
+     */
     protected void firePropertyChange( Object key, Object oldValue, Object newValue ) {
     }
 
     // Implementation classes
     //-------------------------------------------------------------------------
+
+    /**
+     *  Map entry used by {@link BeanMap}.
+     */
     protected static class MyMapEntry extends DefaultMapEntry {        
         private BeanMap owner;
         
+        /**
+         *  Constructs a new <Code>MyMapEntry</Code>.
+         *
+         *  @param owner  the BeanMap this entry belongs to
+         *  @param key  the key for this entry
+         *  @param value  the value for this entry
+         */
         protected MyMapEntry( BeanMap owner, Object key, Object value ) {
             super( key, value );
             this.owner = owner;
         }
 
+        /**
+         *  Sets the value.
+         *
+         *  @param value  the new value for the entry
+         *  @return the old value for the entry
+         */
         public Object setValue(Object value) {
             Object key = getKey();
             Object oldValue = owner.get( key );
@@ -549,7 +695,21 @@ public class BeanMap extends AbstractMap implements Cloneable {
             return oldValue;
         }
     }
-    
+
+    /**
+     *  Creates an array of parameters to pass to the given mutator method.
+     *  If the given object is not the right type to pass to the method 
+     *  directly, it will be converted using {@link #convertType(Class,Object)}.
+     *
+     *  @param method  the mutator method
+     *  @param value  the value to pass to the mutator method
+     *  @return an array containing one object that is either the given value
+     *    or a transformed value
+     *  @throws IllegalAccessException if {@link #convertType(Class,Object)}
+     *    raises it
+     *  @throws IllegalArgumentException if any other exception is raised
+     *    by {@link #convertType(Class,Object)}
+     */
     protected Object[] createWriteMethodArguments( Method method, Object value ) throws IllegalAccessException, ClassCastException {            
         try {
             if ( value != null ) {
@@ -573,7 +733,38 @@ public class BeanMap extends AbstractMap implements Cloneable {
             throw new IllegalArgumentException( e.getMessage() );
         }
     }
-    
+
+    /**
+     * Converts the given value to the given type.  First, reflection is
+     * is used to find a public constructor declared by the given class 
+     * that takes one argument, which must be the precise type of the 
+     * given value.  If such a constructor is found, a new object is
+     * created by passing the given value to that constructor, and the
+     * newly constructed object is returned.<P>
+     *
+     * If no such constructor exists, and the given type is a primitive
+     * type, then the given value is converted to a string using its 
+     * {@link Object#toString() toString()} method, and that string is
+     * parsed into the correct primitve type using, for instance, 
+     * {@link Integer#valueOf(String)} to convert the string into an
+     * <Code>int</Code>.<P>
+     *
+     * If no special constructor exists and the given type is not a 
+     * primitive type, this method returns the original value.
+     *
+     * @param newType  the type to convert the value to
+     * @param value  the value to conert
+     * @return the converted value
+     * @throws NumberFormatException if newType is a primitive type, and 
+     *   the string representation of the given value cannot be converted
+     *   to that type
+     * @throws InstantiationException  if the constructor found with 
+     *   reflection raises it
+     * @throws InvocationTargetExcetpion  if the constructor found with
+     *   reflection raises it
+     * @throws IllegalAccessException  never
+     * @throws IllegalArgumentException  never
+     */
     protected Object convertType( Class newType, Object value ) 
         throws InstantiationException, IllegalAccessException, IllegalArgumentException, InvocationTargetException {
         
@@ -593,16 +784,35 @@ public class BeanMap extends AbstractMap implements Cloneable {
             return value;
         }
     }
-    
+
+    /**
+     *  Returns a transformer for the given primitive type.
+     *
+     *  @param aType  the primitive type whose transformer to return
+     *  @return a transformer that will convert strings into that type,
+     *   or null if the given type is not a primitive type
+     */
     protected Transformer getTypeTransformer( Class aType ) {
         return (Transformer) defaultTransformers.get( aType );
     }
-    
+
+    /**
+     *  Logs the given exception to <Code>System.out</Code>.  Used to display
+     *  warnings while accessing/mutating the bean.
+     *
+     *  @param e  the exception to log
+     */
     protected void logInfo(Exception e) {
         // XXXX: should probably use log4j here instead...
         System.out.println( "INFO: Exception: " + e );
     }
-    
+
+    /**
+     *  Logs the given exception to <Code>System.err</Code>.  Used to display
+     *  errors while accessing/mutating the bean.
+     *
+     *  @param e  the exception to log
+     */
     protected void logWarn(Exception e) {
         // XXXX: should probably use log4j here instead...
         System.out.println( "WARN: Exception: " + e );
diff --git a/src/java/org/apache/commons/collections/BinaryHeap.java b/src/java/org/apache/commons/collections/BinaryHeap.java
index 3df2dba36..20404a77c 100644
--- a/src/java/org/apache/commons/collections/BinaryHeap.java
+++ b/src/java/org/apache/commons/collections/BinaryHeap.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BinaryHeap.java,v 1.9 2002/07/03 02:16:48 mas Exp $
- * $Revision: 1.9 $
- * $Date: 2002/07/03 02:16:48 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BinaryHeap.java,v 1.10 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.10 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -98,10 +98,27 @@ import java.util.Comparator;
 public final class BinaryHeap extends AbstractCollection
     implements PriorityQueue, Buffer
 {
+
+    /**
+     *  The default capacity for a binary heap.
+     */
     protected final static int      DEFAULT_CAPACITY   = 13;
 
+    /**
+     *  The number of elements currently in this heap.
+     */
     protected int                   m_size;
+
+    /**
+     *  The elements in this heap.
+     */
     protected Object[]              m_elements;
+
+    /**
+     *  If true, the first element as determined by the sort order will 
+     *  be returned.  If false, the last element as determiend by the
+     *  sort order will be returned.
+     */
     protected boolean               m_isMinHeap;
     private Comparator              m_comparator;
 
@@ -113,6 +130,10 @@ public final class BinaryHeap extends AbstractCollection
         this( DEFAULT_CAPACITY, true );
     }
 
+    /**
+     *  Constructs a new <Code>BinaryHeap</Code> that will use the given
+     *  comparator to order its elements.
+     */
     public BinaryHeap( Comparator comparator )
     {
         this();
@@ -133,6 +154,14 @@ public final class BinaryHeap extends AbstractCollection
         this( capacity, true );
     }
 
+    /**
+     *  Constructs a new <Code>BinaryHeap</Code>.
+     *
+     *  @param capacity  the initial capacity for the heap
+     *  @param comparator  the comparator to use to order elements
+     *  @exception IllegalArgumentException 
+     *   if <code>capacity</code> is <code>&lt;= 0</code>
+     */
     public BinaryHeap( final int capacity, Comparator comparator )
     {
         this( capacity );
@@ -150,6 +179,13 @@ public final class BinaryHeap extends AbstractCollection
         this( DEFAULT_CAPACITY, isMinHeap );
     }
 
+    /**
+     *  Constructs a new <Code>BinaryHeap</Code>.
+     *
+     *  @param isMinHeap  true to use the order imposed by the given 
+     *    comparator; false to reverse that order
+     *  @param comparator  the comparator to use to order elements
+     */
     public BinaryHeap( final boolean isMinHeap, Comparator comparator )
     {
         this( isMinHeap );
@@ -180,6 +216,16 @@ public final class BinaryHeap extends AbstractCollection
         m_elements = new Object[ capacity + 1 ];
     }
 
+    /**
+     *  Constructs a new <Code>BinaryHeap</Code>.
+     *
+     *  @param capacity  the initial capacity for the heap
+     *  @param isMinHeap  true to use the order imposed by the given 
+     *    comparator; false to reverse that order
+     *  @param comparator  the comparator to use to order elements
+     *  @exception IllegalArgumentException 
+     *   if <code>capacity</code> is <code>&lt;= 0</code>
+     */
     public BinaryHeap( final int capacity, final boolean isMinHeap,
                        Comparator comparator ) 
     {
@@ -409,6 +455,12 @@ public final class BinaryHeap extends AbstractCollection
         m_elements = elements;
     }
 
+    /**
+     *  Returns a string representation of this heap.  The returned string
+     *  is similar to those produced by standard JDK collections.
+     *
+     *  @return  a string representation of this heap
+     */
     public String toString()
     {
         final StringBuffer sb = new StringBuffer();
@@ -519,7 +571,11 @@ public final class BinaryHeap extends AbstractCollection
         return m_size;
     }
 
-
+    /**
+     *  Used by testing code.
+     *
+     *  @return  the otherwise private comparator
+     */
     Comparator comparator() {
         return m_comparator;
     }
diff --git a/src/java/org/apache/commons/collections/BufferUnderflowException.java b/src/java/org/apache/commons/collections/BufferUnderflowException.java
index 6cd7f9bfb..8723d0090 100644
--- a/src/java/org/apache/commons/collections/BufferUnderflowException.java
+++ b/src/java/org/apache/commons/collections/BufferUnderflowException.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BufferUnderflowException.java,v 1.3 2002/08/13 00:46:25 pjack Exp $
- * $Revision: 1.3 $
- * $Date: 2002/08/13 00:46:25 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BufferUnderflowException.java,v 1.4 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.4 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -66,7 +66,7 @@ package org.apache.commons.collections;
  * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
  * @author <a href="mailto:jefft@apache.org">Jeff Turner</a>
  * @since Avalon 4.0
- * @version $Id: BufferUnderflowException.java,v 1.3 2002/08/13 00:46:25 pjack Exp $
+ * @version $Id: BufferUnderflowException.java,v 1.4 2002/08/15 20:04:31 pjack Exp $
  */
 public class BufferUnderflowException extends RuntimeException
 {
@@ -90,7 +90,9 @@ public class BufferUnderflowException extends RuntimeException
         m_throwable = exception;
     }
 
-
+    /**
+     *  Constructs a new <Code>BufferUnderflowException</Code>.
+     */
     public BufferUnderflowException() {
         super();
         m_throwable = null;
diff --git a/src/java/org/apache/commons/collections/BufferUtils.java b/src/java/org/apache/commons/collections/BufferUtils.java
index adeec365b..86a2b41b0 100644
--- a/src/java/org/apache/commons/collections/BufferUtils.java
+++ b/src/java/org/apache/commons/collections/BufferUtils.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BufferUtils.java,v 1.5 2002/08/13 00:46:25 pjack Exp $
- * $Revision: 1.5 $
- * $Date: 2002/08/13 00:46:25 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/BufferUtils.java,v 1.6 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.6 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -69,7 +69,7 @@ import java.util.Iterator;
  *  Contains static utility methods for operating on {@link Buffer} objects.
  *
  *  @author Paul Jack
- *  @version $Id: BufferUtils.java,v 1.5 2002/08/13 00:46:25 pjack Exp $
+ *  @version $Id: BufferUtils.java,v 1.6 2002/08/15 20:04:31 pjack Exp $
  *  @since 2.1
  */
 public class BufferUtils {
@@ -181,6 +181,16 @@ public class BufferUtils {
     }
 
 
+    /**
+     *  Returns a bounded buffer backed by the given buffer.  New elements
+     *  may only be added to the returned buffer if its size is less than
+     *  the specified maximum; otherwise, an {@link IllegalStateException}
+     *  will be thrown.
+     *
+     *  @param buf  the buffer whose size to bind
+     *  @param maxSize  the maximum size of the returned buffer
+     *  @return  a bounded buffer
+     */
     public static Buffer boundedBuffer(Buffer buf, int maxSize) {
         return new BoundedBuffer(buf, maxSize);
     }
diff --git a/src/java/org/apache/commons/collections/CollatingIterator.java b/src/java/org/apache/commons/collections/CollatingIterator.java
index e82eec8e3..a10a5efb1 100644
--- a/src/java/org/apache/commons/collections/CollatingIterator.java
+++ b/src/java/org/apache/commons/collections/CollatingIterator.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/CollatingIterator.java,v 1.3 2002/08/13 00:46:25 pjack Exp $
- * $Revision: 1.3 $
- * $Date: 2002/08/13 00:46:25 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/CollatingIterator.java,v 1.4 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.4 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -73,7 +73,7 @@ import java.util.BitSet;
  * my {@link #next} method will return the lesser of 
  * <code>A.next()</code> and <code>B.next()</code>.
  *
- * @version $Revision: 1.3 $ $Date: 2002/08/13 00:46:25 $
+ * @version $Revision: 1.4 $ $Date: 2002/08/15 20:04:31 $
  * @author Rodney Waldhoff
  * @since 2.1
  */
@@ -81,19 +81,53 @@ public class CollatingIterator implements Iterator {
 
     //------------------------------------------------------------ Constructors
     
+    /**
+     *  Constructs a new <Code>CollatingIterator</Code>.  Natural sort order
+     *  will be used, and child iterators will have to be manually added 
+     *  using the {@link #addIterator(Iterator)} method.
+     */
     public CollatingIterator() {
         this(null,2);
     }
     
+    /**
+     *  Constructs a new <Code>CollatingIterator</Code> that will used the
+     *  specified comparator for ordering.  Child iterators will have to be 
+     *  manually added using the {@link #addIterator(Iterator)} method.
+     *
+     *  @param comp  the comparator to use for ordering, or <Code>null</Code>
+     *    to use natural sort order
+     */
     public CollatingIterator(Comparator comp) {
         this(comp,2);
     }
     
+    /**
+     *  Constructs a new <Code>CollatingIterator</Code> that will used the
+     *  specified comparator for ordering and have the specified initial
+     *  capacity.  Child iterators will have to be 
+     *  manually added using the {@link #addIterator(Iterator)} method.
+     *
+     *  @param comp  the comparator to use for ordering, or <Code>null</Code>
+     *    to use natural sort order
+     *  @param initIterCapacity  the initial capacity for the internal list
+     *    of child iterators
+     */
     public CollatingIterator(Comparator comp, int initIterCapacity) {
         iterators = new ArrayList(initIterCapacity);
         setComparator(comp);
     }
-    
+
+    /**
+     *  Constructs a new <Code>CollatingIterator</Code> that will use the
+     *  specified comparator to provide ordered iteration over the two
+     *  given iterators.
+     *
+     *  @param comp  the comparator to use to sort, or null to use natural
+     *    sort order
+     *  @param a  the first child ordered iterator
+     *  @param b  the second child ordered iterator
+     */
     public CollatingIterator(Comparator comp, Iterator a, Iterator b) {
         this(comp,2);
         addIterator(a);
@@ -129,11 +163,23 @@ public class CollatingIterator implements Iterator {
 
     //------------------------------------------------------- Iterator Methods
 
+    /**
+     *  Returns <Code>true</Code> if any child iterator has remaining elements.
+     *
+     *  @return true if this iterator has remaining elements
+     */
     public boolean hasNext() {
         start();
         return anyValueSet(valueSet) || anyHasNext(iterators);
     }
 
+    /**
+     *  Returns the next ordered element from a child iterator.
+     *
+     *  @return the next ordered element
+     *  @throws NoSuchElementException  if no child iterator has any more
+     *    elements
+     */
     public Object next() throws NoSuchElementException {
         if(!hasNext()) {
             throw new NoSuchElementException();
@@ -150,6 +196,13 @@ public class CollatingIterator implements Iterator {
         }        
     }
 
+    /**
+     *  Removes the last returned element from the child iterator that 
+     *  produced it.
+     *
+     *  @throws IllegalStateException  if there is no last returned element,
+     *    or if the last returned element has already been removed
+     */
     public void remove() {
         if(-1 == lastReturned) {
             throw new NoSuchElementException("No value has been returned yet.");
diff --git a/src/java/org/apache/commons/collections/CollectionUtils.java b/src/java/org/apache/commons/collections/CollectionUtils.java
index cfd5b4b9d..a35ac51a3 100644
--- a/src/java/org/apache/commons/collections/CollectionUtils.java
+++ b/src/java/org/apache/commons/collections/CollectionUtils.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/CollectionUtils.java,v 1.10 2002/08/13 00:26:51 pjack Exp $
- * $Revision: 1.10 $
- * $Date: 2002/08/13 00:26:51 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/CollectionUtils.java,v 1.11 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.11 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -78,7 +78,7 @@ import java.util.Set;
  * @author Rodney Waldhoff
  *
  * @since 1.0
- * @version $Id: CollectionUtils.java,v 1.10 2002/08/13 00:26:51 pjack Exp $
+ * @version $Id: CollectionUtils.java,v 1.11 2002/08/15 20:04:31 pjack Exp $
  */
 public class CollectionUtils {
 
@@ -106,6 +106,12 @@ public class CollectionUtils {
         }
     }
 
+    /**
+     *  Please don't ever instantiate a <Code>CollectionUtils</Code>.
+     */
+    public CollectionUtils() {
+    }
+
     /**
      * Returns a {@link Collection} containing the union
      * of the given {@link Collection}s.
diff --git a/src/java/org/apache/commons/collections/DefaultMapBag.java b/src/java/org/apache/commons/collections/DefaultMapBag.java
index 5f7584bf7..8438cf857 100644
--- a/src/java/org/apache/commons/collections/DefaultMapBag.java
+++ b/src/java/org/apache/commons/collections/DefaultMapBag.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/DefaultMapBag.java,v 1.4 2002/06/16 18:56:19 mas Exp $
- * $Revision: 1.4 $
- * $Date: 2002/06/16 18:56:19 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/DefaultMapBag.java,v 1.5 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.5 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -76,7 +76,10 @@ import java.util.Set;
  * interface to minimize the effort required for target implementations.
  * Subclasses need only to call {@link #setMap(Map)} in their constructor 
  * specifying a map instance that will be used to store the contents of 
- * the bag. 
+ * the bag.<P>
+ *
+ * The map will be used to map bag elements to a number; the number represents
+ * the number of occurrences of that element in the bag.<P>
  *
  * @since 2.0
  * @author Chuck Burdick
@@ -87,10 +90,29 @@ public abstract class DefaultMapBag implements Bag {
    private int _total = 0;
    private int _mods = 0;
 
+
+   /**
+    *  Constructor.  Subclasses should invoke {@link #setMap(Map)} in
+    *  their constructors.
+    */
+   public DefaultMapBag() {
+   }
+
+   /**
+    *  Adds a new element to the bag by incrementing its count in the 
+    *  underlying map.
+    *
+    *  @see Bag#add(Object) 
+    */
    public boolean add(Object o) {
       return add(o, 1);
    }
 
+   /**
+    *  Adds a new element to the bag by incrementing its count in the map.
+    *
+    *  @see Bag#add(Object, int)
+    */
    public boolean add(Object o, int i) {
       _mods++;
       if (i > 0) {
@@ -103,6 +125,11 @@ public abstract class DefaultMapBag implements Bag {
       }
    }
 
+   /**
+    *  Invokes {@link #add(Object)} for each element in the given collection.
+    *
+    *  @see Bag#addAll(Collection)
+    */
    public boolean addAll(Collection c) {
       boolean changed = false;
       Iterator i = c.iterator();
@@ -113,12 +140,22 @@ public abstract class DefaultMapBag implements Bag {
       return changed;
    }
 
+
+   /**
+    *  Clears the bag by clearing the underlying map.
+    */
    public void clear() {
       _mods++;
       _map.clear();
       _total = 0;
    }
 
+   /**
+    *  Determines if the bag contains the given element by checking if the
+    *  underlying map contains the element as a key.
+    *
+    *  @return true if the bag contains the given element
+    */
    public boolean contains(Object o) {
       return _map.containsKey(o);
    }
@@ -144,16 +181,34 @@ public abstract class DefaultMapBag implements Bag {
       return result;
    }
 
+   /**
+    * Returns true if the given object is not null, has the precise type 
+    * of this bag, and contains the same number of occurrences of all the
+    * same elements.
+    *
+    * @param o the object to test for equality
+    * @return true if that object equals this bag
+    */
    public boolean equals(Object o) {
       return (o == this || 
               (o != null && o.getClass().equals(this.getClass()) &&
                ((DefaultMapBag)o)._map.equals(this._map)));
    }
 
+   /**
+    * Returns the hash code of the underlying map.
+    *
+    * @return the hash code of the underlying map
+    */
    public int hashCode() {
       return _map.hashCode();
    }
 
+   /**
+    * Returns true if the underlying map is empty.
+    *
+    * @return true if there are no elements in this bag
+    */
    public boolean isEmpty() {
       return _map.isEmpty();
    }
@@ -231,6 +286,12 @@ public abstract class DefaultMapBag implements Bag {
       return result;
    }
 
+   /**
+    * Remove any members of the bag that are not in the given
+    * bag, respecting cardinality.
+    *
+    * @return true if this call changed the collection
+    */
    public boolean retainAll(Collection c) {
       return retainAll(new HashBag(c));
    }
@@ -261,14 +322,31 @@ public abstract class DefaultMapBag implements Bag {
       return result;
    }
 
+   /**
+    *  Returns an array of all of this bag's elements.
+    *
+    *  @return an array of all of this bag's elements
+    */
    public Object[] toArray() {
       return extractList().toArray();
    }
 
+   /**
+    *  Returns an array of all of this bag's elements.
+    *
+    *  @param a  the array to populate
+    *  @return an array of all of this bag's elements
+    */
    public Object[] toArray(Object[] a) {
       return extractList().toArray(a);
    }
 
+   /**
+    *  Returns the number of occurrence of the given element in this bag
+    *  by looking up its count in the underlying map.
+    *
+    *  @see Bag#getCount(Object)
+    */
    public int getCount(Object o) {
       int result = 0;
       Integer count = MapUtils.getInteger(_map, o);
@@ -278,10 +356,20 @@ public abstract class DefaultMapBag implements Bag {
       return result;
    }
 
+   /**
+    *  Returns an unmodifiable view of the underlying map's key set.
+    *
+    *  @return the set of unique elements in this bag
+    */
    public Set uniqueSet() {
       return Collections.unmodifiableSet(_map.keySet());
    }
 
+   /**
+    *  Returns the number of elements in this bag.
+    *
+    *  @return the number of elements in this bag
+    */
    public int size() {
       return _total;
    }
diff --git a/src/java/org/apache/commons/collections/DefaultMapEntry.java b/src/java/org/apache/commons/collections/DefaultMapEntry.java
index 12f9b1297..d93ca8403 100644
--- a/src/java/org/apache/commons/collections/DefaultMapEntry.java
+++ b/src/java/org/apache/commons/collections/DefaultMapEntry.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/DefaultMapEntry.java,v 1.7 2002/06/16 03:39:40 mas Exp $
- * $Revision: 1.7 $
- * $Date: 2002/06/16 03:39:40 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/DefaultMapEntry.java,v 1.8 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.8 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -74,9 +74,20 @@ public class DefaultMapEntry implements Map.Entry {
     private Object key;
     private Object value;
     
+    /**
+     *  Constructs a new <Code>DefaultMapEntry</Code> with a null key
+     *  and null value.
+     */
     public DefaultMapEntry() {
     }
 
+    /**
+     *  Constructs a new <Code>DefaultMapEntry</Code> with the given
+     *  key and given value.
+     *
+     *  @param key  the key for the entry, may be null
+     *  @param value  the value for the entyr, may be null
+     */
     public DefaultMapEntry(Object key, Object value) {
         this.key = key;
         this.value = value;
@@ -113,16 +124,34 @@ public class DefaultMapEntry implements Map.Entry {
 
     // Map.Entry interface
     //-------------------------------------------------------------------------
+
+    /**
+     *  Returns the key.
+     *
+     *  @return the key 
+     */
     public Object getKey() {
         return key;
     }
 
+
+    /**
+     *  Returns the value.
+     *
+     *  @return the value
+     */
     public Object getValue() {
         return value;
     }
 
     // Properties
     //-------------------------------------------------------------------------    
+
+    /**
+     *  Sets the key.  This method does not modify any map.
+     *
+     *  @param key  the new key
+     */
     public void setKey(Object key) {
         this.key = key;
     }
diff --git a/src/java/org/apache/commons/collections/EnumerationIterator.java b/src/java/org/apache/commons/collections/EnumerationIterator.java
index c60fa2104..2b0072efe 100644
--- a/src/java/org/apache/commons/collections/EnumerationIterator.java
+++ b/src/java/org/apache/commons/collections/EnumerationIterator.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/EnumerationIterator.java,v 1.4 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.4 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/EnumerationIterator.java,v 1.5 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.5 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -79,14 +79,31 @@ public class EnumerationIterator implements Iterator {
 
     private Object last;
     
+    /**
+     *  Constructs a new <Code>EnumerationIterator</Code> that will not
+     *  function until {@link #setEnumeration(Enumeration)} is called.
+     */
     public EnumerationIterator() {
         this(null, null);
     }
-    
+
+    /**
+     *  Constructs a new <Code>EnumerationIterator</Code> that provides
+     *  an iterator view of the given enumeration.
+     *
+     *  @param enumeration  the enumeration to use
+     */
     public EnumerationIterator( Enumeration enumeration ) {
         this(enumeration, null);
     }
 
+    /**
+     *  Constructs a new <Code>EnumerationIterator</Code> that will remove
+     *  elements from the specified collection.
+     *
+     *  @param enum  the enumeration to use
+     *  @param collection  the collection to remove elements form
+     */
     public EnumerationIterator( Enumeration enum, Collection collection ) {
         this.enumeration = enum;
         this.collection = collection;
@@ -95,10 +112,23 @@ public class EnumerationIterator implements Iterator {
 
     // Iterator interface
     //-------------------------------------------------------------------------
+
+    /**
+     *  Returns true if the underlying enumeration has more elements.
+     *
+     *  @return true if the underlying enumeration has more elements
+     *  @throws NullPointerException  if the underlying enumeration is null
+     */
     public boolean hasNext() {
         return enumeration.hasMoreElements();
     }
 
+    /**
+     *  Returns the next object from the enumeration.
+     *
+     *  @return the next object from the enumeration
+     *  @throws NullPointerException if the enumeration is null
+     */
     public Object next() {
         last = enumeration.nextElement();
         return last;
@@ -106,6 +136,8 @@ public class EnumerationIterator implements Iterator {
 
     /**
      * Functions if an associated <code>Collection</code> is known.
+     * If so, the first occurrence of the last returned object from this
+     * iterator will be removed from the collection.
      *
      * @exception IllegalStateException <code>next()</code> not called.
      * @exception UnsupportedOperationException No associated
@@ -129,10 +161,21 @@ public class EnumerationIterator implements Iterator {
 
     // Properties
     //-------------------------------------------------------------------------
+
+    /**
+     *  Returns the underlying enumeration.
+     *
+     *  @return the underlying enumeration
+     */
     public Enumeration getEnumeration() {
         return enumeration;
     }
-    
+
+    /**
+     *  Sets the underlying enumeration.
+     *
+     *  @param enumeration  the new underlying enumeration
+     */
     public void setEnumeration( Enumeration enumeration ) {
         this.enumeration = enumeration;
     }
diff --git a/src/java/org/apache/commons/collections/FactoryUtils.java b/src/java/org/apache/commons/collections/FactoryUtils.java
index 8534a3914..490b77ff4 100644
--- a/src/java/org/apache/commons/collections/FactoryUtils.java
+++ b/src/java/org/apache/commons/collections/FactoryUtils.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/FactoryUtils.java,v 1.3 2002/08/13 01:19:00 pjack Exp $
- * $Revision: 1.3 $
- * $Date: 2002/08/13 01:19:00 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/FactoryUtils.java,v 1.4 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.4 $
+ * $Date: 2002/08/15 20:04:31 $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -69,10 +69,13 @@ import java.lang.reflect.*;
  * objects.
  *
  * @author Arron Bates
- * @version $Revision: 1.3 $
+ * @version $Revision: 1.4 $
  * @since 2.1
  */
 public class FactoryUtils {
+
+  private FactoryUtils() {
+  }
   
   /** Creates a Factory whith a class definition, which will be
    * used to create a new object from an empty constructor.
diff --git a/src/java/org/apache/commons/collections/FastArrayList.java b/src/java/org/apache/commons/collections/FastArrayList.java
index 50f5e6358..abb5616fa 100644
--- a/src/java/org/apache/commons/collections/FastArrayList.java
+++ b/src/java/org/apache/commons/collections/FastArrayList.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/FastArrayList.java,v 1.7 2002/08/13 04:34:08 pjack Exp $
- * $Revision: 1.7 $
- * $Date: 2002/08/13 04:34:08 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/FastArrayList.java,v 1.8 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.8 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -108,7 +108,7 @@ import java.util.ListIterator;
  *
  * @since 1.0
  * @author Craig R. McClanahan
- * @version $Revision: 1.7 $ $Date: 2002/08/13 04:34:08 $
+ * @version $Revision: 1.8 $ $Date: 2002/08/15 20:04:31 $
  */
 
 public class FastArrayList extends ArrayList {
@@ -173,10 +173,21 @@ public class FastArrayList extends ArrayList {
      */
     protected boolean fast = false;
 
+
+    /**
+     *  Returns true if this list is operating in fast mode.
+     *
+     *  @return true if this list is operating in fast mode
+     */
     public boolean getFast() {
         return (this.fast);
     }
 
+    /**
+     *  Sets whether this list will operate in fast mode.
+     *
+     *  @param fast true if the list should operate in fast mode
+     */
     public void setFast(boolean fast) {
         this.fast = fast;
     }
diff --git a/src/java/org/apache/commons/collections/FastHashMap.java b/src/java/org/apache/commons/collections/FastHashMap.java
index 321c298cb..ba1fde233 100644
--- a/src/java/org/apache/commons/collections/FastHashMap.java
+++ b/src/java/org/apache/commons/collections/FastHashMap.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/FastHashMap.java,v 1.8 2002/08/13 04:34:08 pjack Exp $
- * $Revision: 1.8 $
- * $Date: 2002/08/13 04:34:08 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/FastHashMap.java,v 1.9 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.9 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -109,7 +109,7 @@ import java.util.Set;
  *
  * @since 1.0
  * @author Craig R. McClanahan
- * @version $Revision: 1.8 $ $Date: 2002/08/13 04:34:08 $
+ * @version $Revision: 1.9 $ $Date: 2002/08/15 20:04:31 $
  */
 
 public class FastHashMap extends HashMap {
@@ -186,10 +186,20 @@ public class FastHashMap extends HashMap {
      */
     protected boolean fast = false;
 
+    /**
+     *  Returns true if this map is operating in fast mode.
+     *
+     *  @return true if this map is operating in fast mode
+     */
     public boolean getFast() {
         return (this.fast);
     }
 
+    /**
+     *  Sets whether this map is operating in fast mode.
+     *
+     *  @param fast true if this map should operate in fast mode
+     */
     public void setFast(boolean fast) {
         this.fast = fast;
     }
diff --git a/src/java/org/apache/commons/collections/FastTreeMap.java b/src/java/org/apache/commons/collections/FastTreeMap.java
index cd7c0a3c6..7826e8074 100644
--- a/src/java/org/apache/commons/collections/FastTreeMap.java
+++ b/src/java/org/apache/commons/collections/FastTreeMap.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/FastTreeMap.java,v 1.8 2002/08/13 04:34:08 pjack Exp $
- * $Revision: 1.8 $
- * $Date: 2002/08/13 04:34:08 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/FastTreeMap.java,v 1.9 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.9 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -111,7 +111,7 @@ import java.util.TreeMap;
  *
  * @since 1.0
  * @author Craig R. McClanahan
- * @version $Revision: 1.8 $ $Date: 2002/08/13 04:34:08 $
+ * @version $Revision: 1.9 $ $Date: 2002/08/15 20:04:31 $
  */
 
 public class FastTreeMap extends TreeMap {
@@ -189,10 +189,21 @@ public class FastTreeMap extends TreeMap {
      */
     protected boolean fast = false;
 
+
+    /**
+     *  Returns true if this map is operating in fast mode.
+     *
+     *  @return true if this map is operating in fast mode
+     */
     public boolean getFast() {
         return (this.fast);
     }
 
+    /**
+     *  Sets whether this map is operating in fast mode.
+     *
+     *  @param fast true if this map should operate in fast mode
+     */
     public void setFast(boolean fast) {
         this.fast = fast;
     }
diff --git a/src/java/org/apache/commons/collections/FilterIterator.java b/src/java/org/apache/commons/collections/FilterIterator.java
index 8717db082..8e4e75fc6 100644
--- a/src/java/org/apache/commons/collections/FilterIterator.java
+++ b/src/java/org/apache/commons/collections/FilterIterator.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/FilterIterator.java,v 1.5 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.5 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/FilterIterator.java,v 1.6 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.6 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -84,13 +84,31 @@ public class FilterIterator extends ProxyIterator {
     
     
     //-------------------------------------------------------------------------
+
+    /**
+     *  Constructs a new <Code>FilterIterator</Code> that will not function
+     *  until {@link #setIterator(Iterator) setIterator} is invoked.
+     */
     public FilterIterator() {
     }
     
+    /**
+     *  Constructs a new <Code>FilterIterator</Code> that will not function
+     *  until {@link #setPredicate(Predicate) setPredicate} is invoked.
+     *
+     *  @param iterator  the iterator to use
+     */
     public FilterIterator( Iterator iterator ) {
         super( iterator );
     }
 
+    /**
+     *  Constructs a new <Code>FilterIterator</Code> that will use the
+     *  given iterator and predicate.
+     *
+     *  @param iterator  the iterator to use
+     *  @param predicate  the predicate to use
+     */
     public FilterIterator( Iterator iterator, Predicate predicate ) {
         super( iterator );
         this.predicate = predicate;
@@ -99,7 +117,12 @@ public class FilterIterator extends ProxyIterator {
     // Iterator interface
     //-------------------------------------------------------------------------
     
-    /** @return true if there is another object that matches the given predicate */
+    /** 
+     *  Returns true if the underlying iterator contains an object that 
+     *  matches the predicate.
+     *
+     *  @return true if there is another object that matches the predicate 
+     */
     public boolean hasNext() {
         if ( nextObjectSet ) {
             return true;
@@ -108,7 +131,13 @@ public class FilterIterator extends ProxyIterator {
         }
     }
 
-    /** @return the next object which matches the given predicate */
+    /** 
+     *  Returns the next object that matches the predicate.
+     * 
+     *  @return the next object which matches the given predicate
+     *  @throws NoSuchElementException if there are no more elements that
+     *   match the predicate 
+     */
     public Object next() {
         if ( !nextObjectSet ) {
             if (!setNextObject()) {
@@ -122,6 +151,8 @@ public class FilterIterator extends ProxyIterator {
     /**
      * Always throws UnsupportedOperationException as this class 
      * does look-ahead with its internal iterator.
+     *
+     * @throws UnsupportedOperationException  always
      */
     public void remove() {
         throw new UnsupportedOperationException();
diff --git a/src/java/org/apache/commons/collections/FilterListIterator.java b/src/java/org/apache/commons/collections/FilterListIterator.java
index 4c0f1a0f2..acaee9efd 100644
--- a/src/java/org/apache/commons/collections/FilterListIterator.java
+++ b/src/java/org/apache/commons/collections/FilterListIterator.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/FilterListIterator.java,v 1.4 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.4 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/FilterListIterator.java,v 1.5 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.5 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -72,7 +72,7 @@ import java.util.NoSuchElementException;
   * returned by the iterator.
   * 
   * @since 2.0
-  * @version $Revision: 1.4 $ $Date: 2002/06/12 03:59:15 $
+  * @version $Revision: 1.5 $ $Date: 2002/08/15 20:04:31 $
   * @author Rodney Waldhoff
   */
 public class FilterListIterator extends ProxyListIterator {
@@ -80,18 +80,44 @@ public class FilterListIterator extends ProxyListIterator {
     // Constructors    
     //-------------------------------------------------------------------------
     
+    /**
+     *  Constructs a new <Code>FilterListIterator</Code> that will not 
+     *  function until 
+     *  {@link ProxyListIterator#setListIterator(ListIterator) setListIterator}
+     *  and {@link #setPredicate(Predicate) setPredicate} are invoked.
+     */
     public FilterListIterator() {
     }
 
+    /**
+     *  Constructs a new <Code>FilterListIterator</Code> that will not 
+     *  function until {@link #setPredicate(Predicate) setPredicate} is invoked.
+     *
+     *  @param iterator  the iterator to use
+     */
     public FilterListIterator(ListIterator iterator ) {
         super(iterator);
     }
 
+    /**
+     *  Constructs a new <Code>FilterListIterator</Code>.
+     *
+     *  @param iterator  the iterator to use
+     *  @param predicate  the predicate to use
+     */
     public FilterListIterator(ListIterator iterator, Predicate predicate) {
         super(iterator);
         this.predicate = predicate;
     }
 
+    /**
+     *  Constructs a new <Code>FilterListIterator</Code> that will not 
+     *  function until 
+     *  {@link ProxyListIterator#setListIterator(ListIterator) setListIterator}
+     *  is invoked.
+     *
+     *  @param predicate  the predicate to use.
+     */
     public FilterListIterator(Predicate predicate) {
         this.predicate = predicate;
     }
diff --git a/src/java/org/apache/commons/collections/HashBag.java b/src/java/org/apache/commons/collections/HashBag.java
index cf7988787..76b764ea6 100644
--- a/src/java/org/apache/commons/collections/HashBag.java
+++ b/src/java/org/apache/commons/collections/HashBag.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/HashBag.java,v 1.5 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.5 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/HashBag.java,v 1.6 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.6 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -72,6 +72,10 @@ import java.util.HashMap;
  * @author Chuck Burdick
  **/
 public class HashBag extends DefaultMapBag implements Bag {
+
+   /**
+    *  Constructs a new empty <Code>HashBag</Code>.
+    */
    public HashBag() {
       setMap(new HashMap());
    }
diff --git a/src/java/org/apache/commons/collections/IteratorEnumeration.java b/src/java/org/apache/commons/collections/IteratorEnumeration.java
index e1a3ab59c..dc30258e6 100644
--- a/src/java/org/apache/commons/collections/IteratorEnumeration.java
+++ b/src/java/org/apache/commons/collections/IteratorEnumeration.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/IteratorEnumeration.java,v 1.4 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.4 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/IteratorEnumeration.java,v 1.5 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.5 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -73,29 +73,64 @@ public class IteratorEnumeration implements Enumeration {
     
     private Iterator iterator;
     
+    /**
+     *  Constructs a new <Code>IteratorEnumeration</Code> that will not 
+     *  function until {@link #setIterator(Iterator) setIterator} is  
+     *  invoked.
+     */
     public IteratorEnumeration() {
     }
 
+    /**
+     *  Constructs a new <Code>IteratorEnumeration</Code> that will use
+     *  the given iterator. 
+     * 
+     *  @param iterator  the iterator to use
+     */
     public IteratorEnumeration( Iterator iterator ) {
         this.iterator = iterator;
     }
 
     // Iterator interface
     //-------------------------------------------------------------------------
+
+    /**
+     *  Returns true if the underlying iterator has more elements.
+     *
+     *  @return true if the underlying iterator has more elements
+     */
     public boolean hasMoreElements() {
         return iterator.hasNext();
     }
 
+    /**
+     *  Returns the next element from the underlying iterator.
+     *
+     *  @return the next element from the underlying iterator.
+     *  @throws NoSuchElementException  if the underlying iterator has no
+     *    more elements
+     */
     public Object nextElement() {
         return iterator.next();
     }
 
     // Properties
     //-------------------------------------------------------------------------
+
+    /**
+     *  Returns the underlying iterator.
+     * 
+     *  @return the underlying iterator
+     */
     public Iterator getIterator() {
         return iterator;
     }
-    
+
+    /**
+     *  Sets the underlying iterator.
+     *
+     *  @param iterator  the new underlying iterator
+     */
     public void setIterator( Iterator iterator ) {
         this.iterator = iterator;
     }
diff --git a/src/java/org/apache/commons/collections/ListIteratorWrapper.java b/src/java/org/apache/commons/collections/ListIteratorWrapper.java
index 04589d75d..72781c55a 100644
--- a/src/java/org/apache/commons/collections/ListIteratorWrapper.java
+++ b/src/java/org/apache/commons/collections/ListIteratorWrapper.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/ListIteratorWrapper.java,v 1.2 2002/08/13 00:46:25 pjack Exp $
- * $Revision: 1.2 $
- * $Date: 2002/08/13 00:46:25 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/ListIteratorWrapper.java,v 1.3 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.3 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -71,7 +71,7 @@ import java.util.NoSuchElementException;
  * operations of ListIterator.
  * 
  * @author Morgan Delagrange
- * @version $Revision: 1.2 $ $Date: 2002/08/13 00:46:25 $
+ * @version $Revision: 1.3 $ $Date: 2002/08/15 20:04:31 $
  * @since 2.1
  */
 public class ListIteratorWrapper implements ListIterator {
@@ -79,6 +79,12 @@ public class ListIteratorWrapper implements ListIterator {
     // Constructor
     //-------------------------------------------------------------------------
 
+    /**
+     *  Constructs a new <Code>ListIteratorWrapper</Code> that will wrap
+     *  the given iterator.
+     *
+     *  @param iterator  the iterator to wrap
+     */
     public ListIteratorWrapper(Iterator iterator) {
         this.iterator = iterator;
     }
@@ -86,10 +92,22 @@ public class ListIteratorWrapper implements ListIterator {
     // ListIterator interface
     //-------------------------------------------------------------------------
 
+    /**
+     *  Throws {@link UnsupportedOperationException}.
+     *
+     *  @param o  ignored
+     *  @throws UnsupportedOperationException always
+     */
     public void add(Object o) throws UnsupportedOperationException {
         throw new UnsupportedOperationException(UNSUPPORTED_OPERATION_MESSAGE);
     }
 
+
+    /**
+     *  Returns true if there are more elements in the iterator.
+     *
+     *  @return true if there are more elements
+     */
     public boolean hasNext() {
         if (currentIndex == wrappedIteratorIndex) {
             return iterator.hasNext();
@@ -98,6 +116,11 @@ public class ListIteratorWrapper implements ListIterator {
         return true;
     }
 
+    /**
+     *  Returns true if there are previous elements in the iterator.
+     *
+     *  @return true if there are previous elements
+     */
     public boolean hasPrevious() {
         if (currentIndex == 0) {
             return false;
@@ -106,6 +129,12 @@ public class ListIteratorWrapper implements ListIterator {
         return true;
     }
 
+    /**
+     *  Returns the next element from the iterator.
+     *
+     *  @return the next element from the iterator
+     *  @throws NoSuchElementException if there are no more elements
+     */
     public Object next() throws NoSuchElementException {
         if (currentIndex < wrappedIteratorIndex) {
             ++currentIndex;
@@ -119,10 +148,21 @@ public class ListIteratorWrapper implements ListIterator {
         return retval;
     }
 
+    /**
+     *  Returns in the index of the next element.
+     *
+     *  @return the index of the next element
+     */
     public int nextIndex() {
         return currentIndex;
     }
 
+    /**
+     *  Returns the the previous element.
+     *
+     *  @return the previous element
+     *  @throws NoSuchElementException  if there are no previous elements
+     */
     public Object previous() throws NoSuchElementException {
         if (currentIndex == 0) {
             throw new NoSuchElementException();
@@ -132,14 +172,30 @@ public class ListIteratorWrapper implements ListIterator {
         return list.get(currentIndex);    
     }
 
+    /**
+     *  Returns the index of the previous element.
+     *
+     *  @return  the index of the previous element
+     */
     public int previousIndex() {
         return currentIndex - 1;
     }
 
+    /**
+     *  Throws {@link UnsupportedOperationException}.
+     *
+     *  @throws UnsupportedOperationException always
+     */
     public void remove() throws UnsupportedOperationException {
         throw new UnsupportedOperationException(UNSUPPORTED_OPERATION_MESSAGE);
     }
 
+    /**
+     *  Throws {@link UnsupportedOperationException}.
+     *
+     *  @param o  ignored
+     *  @throws UnsupportedOperationException always
+     */
     public void set(Object o) throws UnsupportedOperationException {
         throw new UnsupportedOperationException(UNSUPPORTED_OPERATION_MESSAGE);
     }
diff --git a/src/java/org/apache/commons/collections/ListUtils.java b/src/java/org/apache/commons/collections/ListUtils.java
index d3a01daaa..0d4e406f1 100644
--- a/src/java/org/apache/commons/collections/ListUtils.java
+++ b/src/java/org/apache/commons/collections/ListUtils.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/ListUtils.java,v 1.6 2002/08/13 01:19:00 pjack Exp $
- * $Revision: 1.6 $
- * $Date: 2002/08/13 01:19:00 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/ListUtils.java,v 1.7 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.7 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -77,6 +77,22 @@ import java.util.ListIterator;
  */
 public class ListUtils
 {
+
+    /**
+     *  Please don't ever instantiate a <Code>ListUtils</Code>.
+     */
+    public ListUtils() {
+    }
+
+    /**
+     *  Returns a new list containing all elements that are contained in
+     *  both given lists.
+     *
+     *  @param list1  the first list
+     *  @param list2  the second list
+     *  @return  the intersection of those two lists
+     *  @throws NullPointerException if either list is null
+     */
     public static List intersection( final List list1, final List list2 )
     {
         final ArrayList result = new ArrayList();
@@ -95,6 +111,21 @@ public class ListUtils
         return result;
     }
 
+
+    /**
+     *  Subtracts all elements in the second list from the first list,
+     *  placing the results in a new list.
+     *  This differs from {@link List#removeAll(Collection)} in that
+     *  cardinality is respected; if <Code>list1</Code> contains two
+     *  occurrences of <Code>null</Code> and <Code>list2</Code> only
+     *  contains one occurrence, then the returned list will still contain
+     *  one occurrence.
+     *
+     *  @param list1  the list to subtract from
+     *  @param list2  the lsit to subtract
+     *  @return  a new list containing the results
+     *  @throws NullPointerException if either list is null
+     */
     public static List subtract( final List list1, final List list2 )
     {
         final ArrayList result = new ArrayList( list1 );
@@ -108,12 +139,32 @@ public class ListUtils
         return result;
     }
 
+    /**
+     *  Returns the sum of the given lists.  This is their intersection
+     *  subtracted from their union.
+     *
+     *  @param list1  the first list 
+     *  @param list2  the second list
+     *  @return  a new list containing the sum of those lists
+     *  @throws NullPointerException if either list is null
+     */ 
     public static List sum( final List list1, final List list2 )
     {
         return subtract( union( list1, list2 ),
                          intersection( list1, list2 ) );
     }
 
+
+    /**
+     *  Returns a new list containing the second list appended to the
+     *  first list.  The {@link List#addAll(Collection)} operation is
+     *  used to append the two given lists into a new list.
+     *
+     *  @param list1  the first list 
+     *  @param list2  the second list
+     *  @return  a new list containing the union of those lists
+     *  @throws NullPointerException if either list is null
+     */
     public static List union( final List list1, final List list2 )
     {
         final ArrayList result = new ArrayList( list1 );
diff --git a/src/java/org/apache/commons/collections/MapUtils.java b/src/java/org/apache/commons/collections/MapUtils.java
index 02f501171..41c6810cb 100644
--- a/src/java/org/apache/commons/collections/MapUtils.java
+++ b/src/java/org/apache/commons/collections/MapUtils.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/MapUtils.java,v 1.7 2002/08/13 01:19:00 pjack Exp $
- * $Revision: 1.7 $
- * $Date: 2002/08/13 01:19:00 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/MapUtils.java,v 1.8 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.8 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -62,12 +62,25 @@ package org.apache.commons.collections;
 
 import java.io.*;
 import java.text.*;
+import java.text.NumberFormat;
 import java.util.*;
 
-/** A helper class for using {@link Map Map} instances.
+/** A helper class for using {@link Map Map} instances.<P>
   *
   * It contains various typesafe methods
-  * as well as other useful features like deep copying
+  * as well as other useful features like deep copying.<P>
+  *
+  * It also provides the following decorators:
+  *
+  *  <UL>
+  *  <LI>{@link #boundedMap(Map,int)}
+  *  <LI>{@link #fixedSizeMap(Map)}
+  *  <LI>{@link #fixedSizeSortedMap(SortedMap)}
+  *  <LI>{@link #lazyMap(Map,Factory)}
+  *  <LI>{@link #lazySortedMap(SortedMap,Factory)}
+  *  <LI>{@link #predicatedMap(Map,Predicate,Predicate)}
+  *  <LI>{@link #predicatedSortedMap(SortedMap,Predicate,Predicate)}
+  *  </UL>
   *
   * @since 1.0
   * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
@@ -78,11 +91,24 @@ import java.util.*;
 public class MapUtils {
 
     private static int debugIndent = 0;
-    
-    
+
+    /**
+     *  Please don't instantiate a <Code>MapUtils</Code>.
+     */
+    public MapUtils() {
+    }    
     
     // Type safe getters
     //-------------------------------------------------------------------------
+
+    /**
+     *  Synonym for {@link Map#get(Object)}.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key whose value to look up in that map
+     *  @return null if the map is null; or the result of 
+     *     <Code>map.get(key)</Code>
+     */
     public static Object getObject( Map map, Object key ) {
         if ( map != null ) {
             return map.get( key );
@@ -90,6 +116,16 @@ public class MapUtils {
         return null;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a string.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key whose value to look up in that map
+     *  @return  null if the map is null; null if the value mapped by that
+     *    key is null; or the <Code>toString()</Code> 
+     *     result of the value for that key
+     */
     public static String getString( Map map, Object key ) {
         if ( map != null ) {
             Object answer = map.get( key );
@@ -100,6 +136,25 @@ public class MapUtils {
         return null;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a {@link Boolean}.  If the map is null, this method returns null.
+     *  If the value mapped by the given key is a 
+     *  {@link Boolean}, then it is returned as-is.  Otherwise, if the value
+     *  is a string, then if that string ignoring case equals "true", then
+     *  a true {@link Boolean} is returned.  Any other string value will
+     *  result in a false {@link Boolean} being returned.  OR, if the value
+     *  is a {@link Number}, and that {@link Number} is 0, then a false
+     *  {@link Boolean} is returned.  Any other {@link Number} value results
+     *  in a true {@link Boolean} being returned.<P>
+     *
+     *  Any value that is not a {@link Boolean}, {@link String} or 
+     *  {@link Number} results in null being returned.<P>
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key whose value to look up in that map
+     *  @return  a {@link Boolean} or null
+     */
     public static Boolean getBoolean( Map map, Object key ) {
         if ( map != null ) {
             Object answer = map.get( key );
@@ -121,6 +176,22 @@ public class MapUtils {
         return null;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a {@link Number}.  If the map is null, this method returns null.
+     *  Otherwise, if the key maps to a {@link Number}, then that number
+     *  is returned as-is.  Otherwise, if the key maps to a {@link String},
+     *  that string is parsed into a number using the system default
+     *  {@link NumberFormat}.<P>
+     *
+     *  If the value is not a {@link Number} or a {@link String}, or if
+     *  the value is a {@link String} that cannot be parsed into a 
+     *  {@link Number}, then null is returned.<P>
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key whose value to look up in that map
+     *  @return  a {@link Number} or null
+     */
     public static Number getNumber( Map map, Object key ) {
         if ( map != null ) {
             Object answer = map.get( key );
@@ -143,6 +214,16 @@ public class MapUtils {
         return null;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a {@link Byte}.  First, {@link #getNumber(Map,Object)} is invoked.
+     *  If the result is null, then null is returned.  Otherwise, the 
+     *  byte value of the resulting {@link Number} is returned.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key whose value to look up in that map
+     *  @return  a {@link Byte} or null
+     */
     public static Byte getByte( Map map, Object key ) {
         Number answer = getNumber( map, key );
         if ( answer == null ) {
@@ -155,6 +236,16 @@ public class MapUtils {
         return new Byte( answer.byteValue() );
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a {@link Short}.  First, {@link #getNumber(Map,Object)} is invoked.
+     *  If the result is null, then null is returned.  Otherwise, the 
+     *  short value of the resulting {@link Number} is returned.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key whose value to look up in that map
+     *  @return  a {@link Short} or null
+     */
     public static Short getShort( Map map, Object key ) {
         Number answer = getNumber( map, key );
         if ( answer == null ) {
@@ -167,6 +258,16 @@ public class MapUtils {
         return new Short( answer.shortValue() );
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  an {@link Integer}.  First, {@link #getNumber(Map,Object)} is invoked.
+     *  If the result is null, then null is returned.  Otherwise, the 
+     *  integer value of the resulting {@link Number} is returned.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key whose value to look up in that map
+     *  @return  an {@link Integer} or null
+     */
     public static Integer getInteger( Map map, Object key ) {
         Number answer = getNumber( map, key );
         if ( answer == null ) {
@@ -179,6 +280,16 @@ public class MapUtils {
         return new Integer( answer.intValue() );
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a {@link Long}.  First, {@link #getNumber(Map,Object)} is invoked.
+     *  If the result is null, then null is returned.  Otherwise, the 
+     *  long value of the resulting {@link Number} is returned.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key whose value to look up in that map
+     *  @return  a {@link Long} or null
+     */
     public static Long getLong( Map map, Object key ) {
         Number answer = getNumber( map, key );
         if ( answer == null ) {
@@ -191,6 +302,16 @@ public class MapUtils {
         return new Long( answer.longValue() );
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a {@link Float}.  First, {@link #getNumber(Map,Object)} is invoked.
+     *  If the result is null, then null is returned.  Otherwise, the 
+     *  float value of the resulting {@link Number} is returned.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key whose value to look up in that map
+     *  @return  a {@link Float} or null
+     */
     public static Float getFloat( Map map, Object key ) {
         Number answer = getNumber( map, key );
         if ( answer == null ) {
@@ -203,6 +324,16 @@ public class MapUtils {
         return new Float( answer.floatValue() );
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a {@link Double}.  First, {@link #getNumber(Map,Object)} is invoked.
+     *  If the result is null, then null is returned.  Otherwise, the 
+     *  double value of the resulting {@link Number} is returned.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key whose value to look up in that map
+     *  @return  a {@link Double} or null
+     */
     public static Double getDouble( Map map, Object key ) {
         Number answer = getNumber( map, key );
         if ( answer == null ) {
@@ -215,6 +346,16 @@ public class MapUtils {
         return new Double( answer.doubleValue() );
     }
 
+    /**
+     *  Looks up the given key in the given map, returning another map.
+     *  If the given map is null or if the given key doesn't map to another
+     *  map, then this method returns null.  Otherwise the mapped map is
+     *  returned.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key whose value to look up in that map
+     *  @return  a {@link Map} or null
+     */
     public static Map getMap( Map map, Object key ) {
         if ( map != null ) {
             Object answer = map.get( key );
@@ -227,6 +368,17 @@ public class MapUtils {
 
     // Type safe getters with default values
     //-------------------------------------------------------------------------
+
+    /**
+     *  Looks up the given key in the given map, converting null into the
+     *  given default value.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key of the value to look up in that map
+     *  @param defaultValue  what to return if the value is null
+     *  @return  the value in the map, or defaultValue if the original value
+     *    is null or the map is null
+     */
     public static Object getObject( Map map, Object key, Object defaultValue ) {
         if ( map != null ) {
             Object answer = map.get( key );
@@ -237,6 +389,18 @@ public class MapUtils {
         return defaultValue;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a string, using the default value if the the conversion fails.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key of the value to look up in that map
+     *  @param defaultValue  what to return if the value is null or if the
+     *     conversion fails
+     *  @return  the value in the map as a string, or defaultValue if the 
+     *    original value is null, the map is null or the string conversion
+     *    fails
+     */
     public static String getString( Map map, Object key, String defaultValue ) {
         String answer = getString( map, key );
         if ( answer == null ) {
@@ -245,6 +409,18 @@ public class MapUtils {
         return answer;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a boolean, using the default value if the the conversion fails.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key of the value to look up in that map
+     *  @param defaultValue  what to return if the value is null or if the
+     *     conversion fails
+     *  @return  the value in the map as a boolean, or defaultValue if the 
+     *    original value is null, the map is null or the boolean conversion
+     *    fails
+     */
     public static Boolean getBoolean( Map map, Object key, Boolean defaultValue ) {
         Boolean answer = getBoolean( map, key );
         if ( answer == null ) {
@@ -253,6 +429,18 @@ public class MapUtils {
         return answer;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a number, using the default value if the the conversion fails.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key of the value to look up in that map
+     *  @param defaultValue  what to return if the value is null or if the
+     *     conversion fails
+     *  @return  the value in the map as a number, or defaultValue if the 
+     *    original value is null, the map is null or the number conversion
+     *    fails
+     */
     public static Number getNumber( Map map, Object key, Number defaultValue ) {
         Number answer = getNumber( map, key );
         if ( answer == null ) {
@@ -261,6 +449,18 @@ public class MapUtils {
         return answer;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a byte, using the default value if the the conversion fails.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key of the value to look up in that map
+     *  @param defaultValue  what to return if the value is null or if the
+     *     conversion fails
+     *  @return  the value in the map as a number, or defaultValue if the 
+     *    original value is null, the map is null or the number conversion
+     *    fails
+     */
     public static Byte getByte( Map map, Object key, Byte defaultValue ) {
         Byte answer = getByte( map, key );
         if ( answer == null ) {
@@ -269,6 +469,18 @@ public class MapUtils {
         return answer;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a short, using the default value if the the conversion fails.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key of the value to look up in that map
+     *  @param defaultValue  what to return if the value is null or if the
+     *     conversion fails
+     *  @return  the value in the map as a number, or defaultValue if the 
+     *    original value is null, the map is null or the number conversion
+     *    fails
+     */
     public static Short getShort( Map map, Object key, Short defaultValue ) {
         Short answer = getShort( map, key );
         if ( answer == null ) {
@@ -277,6 +489,18 @@ public class MapUtils {
         return answer;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  an integer, using the default value if the the conversion fails.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key of the value to look up in that map
+     *  @param defaultValue  what to return if the value is null or if the
+     *     conversion fails
+     *  @return  the value in the map as a number, or defaultValue if the 
+     *    original value is null, the map is null or the number conversion
+     *    fails
+     */
     public static Integer getInteger( Map map, Object key, Integer defaultValue ) {
         Integer answer = getInteger( map, key );
         if ( answer == null ) {
@@ -285,6 +509,18 @@ public class MapUtils {
         return answer;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a long, using the default value if the the conversion fails.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key of the value to look up in that map
+     *  @param defaultValue  what to return if the value is null or if the
+     *     conversion fails
+     *  @return  the value in the map as a number, or defaultValue if the 
+     *    original value is null, the map is null or the number conversion
+     *    fails
+     */
     public static Long getLong( Map map, Object key, Long defaultValue ) {
         Long answer = getLong( map, key );
         if ( answer == null ) {
@@ -293,6 +529,18 @@ public class MapUtils {
         return answer;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a float, using the default value if the the conversion fails.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key of the value to look up in that map
+     *  @param defaultValue  what to return if the value is null or if the
+     *     conversion fails
+     *  @return  the value in the map as a number, or defaultValue if the 
+     *    original value is null, the map is null or the number conversion
+     *    fails
+     */
     public static Float getFloat( Map map, Object key, Float defaultValue ) {
         Float answer = getFloat( map, key );
         if ( answer == null ) {
@@ -301,6 +549,18 @@ public class MapUtils {
         return answer;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a double, using the default value if the the conversion fails.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key of the value to look up in that map
+     *  @param defaultValue  what to return if the value is null or if the
+     *     conversion fails
+     *  @return  the value in the map as a number, or defaultValue if the 
+     *    original value is null, the map is null or the number conversion
+     *    fails
+     */
     public static Double getDouble( Map map, Object key, Double defaultValue ) {
         Double answer = getDouble( map, key );
         if ( answer == null ) {
@@ -309,6 +569,18 @@ public class MapUtils {
         return answer;
     }
 
+    /**
+     *  Looks up the given key in the given map, converting the result into
+     *  a map, using the default value if the the conversion fails.
+     *
+     *  @param map  the map whose value to look up
+     *  @param key  the key of the value to look up in that map
+     *  @param defaultValue  what to return if the value is null or if the
+     *     conversion fails
+     *  @return  the value in the map as a number, or defaultValue if the 
+     *    original value is null, the map is null or the map conversion
+     *    fails
+     */
     public static Map getMap( Map map, Object key, Map defaultValue ) {
         Map answer = getMap( map, key );
         if ( answer == null ) {
@@ -319,6 +591,10 @@ public class MapUtils {
 
     // Conversion methods
     //-------------------------------------------------------------------------
+
+    /**
+     *  Synonym for <Code>new Properties(input)</COde>.
+     */
     public static Properties toProperties(Map input) {
         Properties answer = new Properties();
         if ( input != null ) {
@@ -334,6 +610,14 @@ public class MapUtils {
 
     // Printing methods
     //-------------------------------------------------------------------------
+
+    /**
+     *  Prints the given map with nice line breaks.
+     *
+     *  @param out  the stream to print to
+     *  @param key  the key that maps to the map in some other map
+     *  @param map  the map to print
+     */
     public static synchronized void verbosePrint( PrintStream out, Object key, Map map ) {
         debugPrintIndent( out );
         out.println( key + " = " );
@@ -359,6 +643,13 @@ public class MapUtils {
         out.println( "}" );
     }
 
+    /**
+     *  Prints the given map with nice line breaks.
+     *
+     *  @param out  the stream to print to
+     *  @param key  the key that maps to the map in some other map
+     *  @param map  the map to print
+     */
     public static synchronized void debugPrint( PrintStream out, Object key, Map map ) {
         debugPrintIndent( out );
         out.println( key + " = " );
@@ -391,12 +682,23 @@ public class MapUtils {
 
     // Implementation methods
     //-------------------------------------------------------------------------
+
+    /**
+     *  Writes indentation to the given stream.
+     *
+     *  @param out   the stream to indent
+     */
     protected static void debugPrintIndent( PrintStream out ) {
         for ( int i = 0; i < debugIndent; i++ ) {
             out.print( "    " );
         }
     }
     
+    /**
+     *  Logs the given exception to <Code>System.out</Code>.
+     *
+     *  @param e  the exception to log
+     */
     protected static void logInfo(Exception e) {
         // mapX: should probably use log4j here instead...
         System.out.println( "INFO: Exception: " + e );
diff --git a/src/java/org/apache/commons/collections/Predicate.java b/src/java/org/apache/commons/collections/Predicate.java
index 136f2c529..960d9dd23 100644
--- a/src/java/org/apache/commons/collections/Predicate.java
+++ b/src/java/org/apache/commons/collections/Predicate.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Predicate.java,v 1.4 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.4 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Predicate.java,v 1.5 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.5 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -68,7 +68,10 @@ package org.apache.commons.collections;
   */
 public interface Predicate {
 
-    /** @return true if the input object matches this predicate, else returns false
+    /**
+      *  Returns true if the input object matches this predicate. 
+      *
+      * @return true if the input object matches this predicate, else returns false
       */
     public boolean evaluate(Object input);
 }
diff --git a/src/java/org/apache/commons/collections/PredicateUtils.java b/src/java/org/apache/commons/collections/PredicateUtils.java
index 1f9adb866..078dadce4 100644
--- a/src/java/org/apache/commons/collections/PredicateUtils.java
+++ b/src/java/org/apache/commons/collections/PredicateUtils.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/PredicateUtils.java,v 1.4 2002/08/13 00:46:25 pjack Exp $
- * $Revision: 1.4 $
- * $Date: 2002/08/13 00:46:25 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/PredicateUtils.java,v 1.5 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.5 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -86,7 +86,7 @@ import java.util.SortedMap;
  * And, Or and instanceof.
  * 
  * @author Stephen Colebourne
- * @version $Id: PredicateUtils.java,v 1.4 2002/08/13 00:46:25 pjack Exp $
+ * @version $Id: PredicateUtils.java,v 1.5 2002/08/15 20:04:31 pjack Exp $
  * @since 2.1
  */
 public class PredicateUtils {
@@ -250,7 +250,7 @@ public class PredicateUtils {
     /**
      * Predicate that checks the type of an object
      */
-    public static class InstanceofPredicate implements Predicate {
+    private static class InstanceofPredicate implements Predicate {
         private final Class iType;
     
     	/**
diff --git a/src/java/org/apache/commons/collections/ProxyIterator.java b/src/java/org/apache/commons/collections/ProxyIterator.java
index dbac9fd78..705fadf94 100644
--- a/src/java/org/apache/commons/collections/ProxyIterator.java
+++ b/src/java/org/apache/commons/collections/ProxyIterator.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/ProxyIterator.java,v 1.4 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.4 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/ProxyIterator.java,v 1.5 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.5 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -66,7 +66,7 @@ import java.util.Iterator;
   *
   * @since 1.0
   * @see ProxyListIterator
-  * @version $Revision: 1.4 $ $Date: 2002/06/12 03:59:15 $
+  * @version $Revision: 1.5 $ $Date: 2002/08/15 20:04:31 $
   *
   * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
   */
@@ -76,24 +76,50 @@ public class ProxyIterator implements Iterator {
     /** Holds value of property iterator. */
     private Iterator iterator;
     
-    
+    /**
+     *  Constructs a new <Code>ProxyIterator</Code> that will not function
+     *  until {@link #setIterator(Iterator)} is called.
+     */
     public ProxyIterator() {
     }
     
+    /**
+     *  Constructs a new <Code>ProxyIterator</Code> that will use the
+     *  given iterator.
+     *
+     *  @param iterator  the underyling iterator
+     */
     public ProxyIterator( Iterator iterator ) {
         this.iterator = iterator;
     }
 
     // Iterator interface
     //-------------------------------------------------------------------------
+
+    /**
+     *  Returns true if the underlying iterator has more elements.
+     *
+     *  @return true if the underlying iterator has more elements
+     */
     public boolean hasNext() {
         return getIterator().hasNext();
     }
 
+    /**
+     *  Returns the next element from the underlying iterator.
+     *
+     *  @return the next element from the underlying iterator
+     *  @throws NoSuchElementException  if the underlying iterator 
+     *    raises it because it has no more elements
+     */
     public Object next() {
         return getIterator().next();
     }
 
+    /**
+     *  Removes the last returned element from the collection that spawned
+     *  the underlying iterator.
+     */
     public void remove() {
         getIterator().remove();
     }
diff --git a/src/java/org/apache/commons/collections/ProxyListIterator.java b/src/java/org/apache/commons/collections/ProxyListIterator.java
index b0c2d76fc..82039b5c8 100644
--- a/src/java/org/apache/commons/collections/ProxyListIterator.java
+++ b/src/java/org/apache/commons/collections/ProxyListIterator.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/ProxyListIterator.java,v 1.2 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.2 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/ProxyListIterator.java,v 1.3 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.3 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -68,7 +68,7 @@ import java.util.ListIterator;
  *
  * @since 2.0
  * @see ProxyIterator
- * @version $Revision: 1.2 $ $Date: 2002/06/12 03:59:15 $
+ * @version $Revision: 1.3 $ $Date: 2002/08/15 20:04:31 $
  * @author Rodney Waldhoff
  */
 public class ProxyListIterator implements ListIterator {
@@ -76,9 +76,20 @@ public class ProxyListIterator implements ListIterator {
     // Constructor
     //-------------------------------------------------------------------------
 
+    /**
+     *  Constructs a new <Code>ProxyListIterator</Code> that will not 
+     *  function until {@link #setListIterator(ListIterator) setListIterator}
+     *  is invoked.
+     */
     public ProxyListIterator() {
     }
 
+    /**
+     *  Constructs a new <Code>ProxyListIterator</Code> that will use the
+     *  given list iterator.
+     *
+     *  @param iterator  the list iterator to use
+     */
     public ProxyListIterator(ListIterator iterator) {
         this.iterator = iterator;
     }
@@ -86,38 +97,83 @@ public class ProxyListIterator implements ListIterator {
     // ListIterator interface
     //-------------------------------------------------------------------------
 
+    /**
+     *  Invokes the underlying {@link ListIterator#add(Object)} method.
+     *
+     *  @throws NullPointerException  if the underyling iterator is null
+     */
     public void add(Object o) {
         getListIterator().add(o);
     }
 
+    /**
+     *  Invokes the underlying {@link ListIterator#hasNext()} method.
+     *
+     *  @throws NullPointerException  if the underyling iterator is null
+     */
     public boolean hasNext() {
         return getListIterator().hasNext();
     }
 
+    /**
+     *  Invokes the underlying {@link ListIterator#hasPrevious()} method.
+     *
+     *  @throws NullPointerException  if the underyling iterator is null
+     */
     public boolean hasPrevious() {
         return getListIterator().hasPrevious();
     }
 
+    /**
+     *  Invokes the underlying {@link ListIterator#next()} method.
+     *
+     *  @throws NullPointerException  if the underyling iterator is null
+     */
     public Object next() {
         return getListIterator().next();
     }
 
+    /**
+     *  Invokes the underlying {@link ListIterator#nextIndex()} method.
+     *
+     *  @throws NullPointerException  if the underyling iterator is null
+     */
     public int nextIndex() {
         return getListIterator().nextIndex();
     }
 
+    /**
+     *  Invokes the underlying {@link ListIterator#previous()} method.
+     *
+     *  @throws NullPointerException  if the underyling iterator is null
+     */
     public Object previous() {
         return getListIterator().previous();
     }
 
+    /**
+     *  Invokes the underlying {@link ListIterator#previousIndex()} method.
+     *
+     *  @throws NullPointerException  if the underyling iterator is null
+     */
     public int previousIndex() {
         return getListIterator().previousIndex();
     }
 
+    /**
+     *  Invokes the underlying {@link ListIterator#remove()} method.
+     *
+     *  @throws NullPointerException  if the underyling iterator is null
+     */
     public void remove() {
         getListIterator().remove();
     }
 
+    /**
+     *  Invokes the underlying {@link ListIterator#set(Object)} method.
+     *
+     *  @throws NullPointerException  if the underyling iterator is null
+     */
     public void set(Object o) {
         getListIterator().set(o);
     }
diff --git a/src/java/org/apache/commons/collections/ProxyMap.java b/src/java/org/apache/commons/collections/ProxyMap.java
index ee9855c54..303fcdacb 100644
--- a/src/java/org/apache/commons/collections/ProxyMap.java
+++ b/src/java/org/apache/commons/collections/ProxyMap.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/ProxyMap.java,v 1.4 2002/08/12 22:51:13 pjack Exp $
- * $Revision: 1.4 $
- * $Date: 2002/08/12 22:51:13 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/ProxyMap.java,v 1.5 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.5 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -97,58 +97,100 @@ public abstract class ProxyMap implements Map {
         this.map = map;
     }
 
+    /**
+     *  Invokes the underlying {@link Map#clear()} method.
+     */
     public void clear() {
         map.clear();
     }
 
+    /**
+     *  Invokes the underlying {@link Map#containsKey(Object)} method.
+     */
     public boolean containsKey(Object key) {
         return map.containsKey(key);
     }
 
+    /**
+     *  Invokes the underlying {@link Map#containsValue(Object)} method.
+     */
     public boolean containsValue(Object value) {
         return map.containsValue(value);
     }
 
+    /**
+     *  Invokes the underlying {@link Map#entrySet()} method.
+     */
     public Set entrySet() {
         return map.entrySet();
     }
 
+    /**
+     *  Invokes the underlying {@link Map#equals(Object)} method.
+     */
     public boolean equals(Object m) {
         return map.equals(m);
     }
 
+    /**
+     *  Invokes the underlying {@link Map#get(Object)} method.
+     */
     public Object get(Object key) {
         return map.get(key);
     }
 
+    /**
+     *  Invokes the underlying {@link Map#hashCode()} method.
+     */
     public int hashCode() {
         return map.hashCode();
     }
 
+    /**
+     *  Invokes the underlying {@link Map#isEmpty()} method.
+     */
     public boolean isEmpty() {
         return map.isEmpty();
     }
 
+    /**
+     *  Invokes the underlying {@link Map#keySet()} method.
+     */
     public Set keySet() {
         return map.keySet();
     }
 
+    /**
+     *  Invokes the underlying {@link Map#put(Object,Object)} method.
+     */
     public Object put(Object key, Object value) {
         return map.put(key, value);
     }
 
+    /**
+     *  Invokes the underlying {@link Map#putAll(Map)} method.
+     */
     public void putAll(Map t) {
         map.putAll(t);
     }
 
+    /**
+     *  Invokes the underlying {@link Map#remove(Object)} method.
+     */
     public Object remove(Object key) {
         return map.remove(key);
     }
 
+    /**
+     *  Invokes the underlying {@link Map#size()} method.
+     */
     public int size() {
         return map.size();
     }
 
+    /**
+     *  Invokes the underlying {@link Map#values()} method.
+     */
     public Collection values() {
         return map.values();
     }
diff --git a/src/java/org/apache/commons/collections/SequencedHashMap.java b/src/java/org/apache/commons/collections/SequencedHashMap.java
index faae1018f..8e4ab170e 100644
--- a/src/java/org/apache/commons/collections/SequencedHashMap.java
+++ b/src/java/org/apache/commons/collections/SequencedHashMap.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/SequencedHashMap.java,v 1.12 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.12 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/SequencedHashMap.java,v 1.13 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.13 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -269,25 +269,35 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
   }
 
   // per Map.size()
+
+  /**
+   *  Implements {@link Map#size()}.
+   */
   public int size() {
     // use the underlying Map's size since size is not maintained here.
     return entries.size();
   }
 
-  // per Map.isEmpty()
+  /**
+   *  Implements {@link Map#isEmpty()}.
+   */
   public boolean isEmpty() {
     // for quick check whether the map is entry, we can check the linked list
     // and see if there's anything in it.
     return sentinel.next == sentinel;
   }
 
-  // per Map.containsKey(Object)
+  /**
+   *  Implements {@link Map#containsKey(Object)}.
+   */
   public boolean containsKey(Object key) {
     // pass on to underlying map implementation
     return entries.containsKey(key);
   }
 
-  // per Map.containsValue(Object)
+  /**
+   *  Implements {@link Map#containsValue(Object)}.
+   */
   public boolean containsValue(Object value) {
     // unfortunately, we cannot just pass this call to the underlying map
     // because we are mapping keys to entries, not keys to values.  The
@@ -309,7 +319,9 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
     return false;      
   }
 
-  // per Map.get(Object)
+  /**
+   *  Implements {@link Map#get(Object)}.
+   */
   public Object get(Object o) {
     // find entry for the specified key object
     Entry entry = (Entry)entries.get(o);
@@ -442,7 +454,9 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
     return sentinel.prev.getValue();
   }
 
-  // per Map.put(Object,Object)
+  /**
+   *  Implements {@link Map#put(Object, Object)}.
+   */
   public Object put(Object key, Object value) {
     modCount++;
 
@@ -477,7 +491,9 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
     return oldValue;
   }
 
-  // per Map.remove(Object)
+  /**
+   *  Implements {@link Map#remove(Object)}.
+   */
   public Object remove(Object key) {
     Entry e = removeImpl(key);
     return (e == null) ? null : e.getValue();
@@ -513,7 +529,9 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
     }
   }
 
-  // per Map.clear()
+  /**
+   *  Implements {@link Map#clear()}.
+   */
   public void clear() {
     modCount++;
 
@@ -525,7 +543,9 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
     sentinel.prev = sentinel;
   }
 
-  // per Map.equals(Object)
+  /**
+   *  Implements {@link Map#equals(Object)}.
+   */
   public boolean equals(Object obj) {
     if(obj == null) return false;
     if(obj == this) return true;
@@ -535,7 +555,9 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
     return entrySet().equals(((Map)obj).entrySet());
   }
 
-  // per Map.hashCode()
+  /**
+   *  Implements {@link Map#hashCode()}.
+   */
   public int hashCode() {
     return entrySet().hashCode();
   }
@@ -563,7 +585,9 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
     return buf.toString();
   }
 
-  // per Map.keySet()
+  /**
+   *  Implements {@link Map#keySet()}.
+   */
   public Set keySet() {
     return new AbstractSet() {
 
@@ -591,7 +615,9 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
     };
   }
 
-  // per Map.values()
+  /**
+   *  Implements {@link Map#values()}.
+   */
   public Collection values() {
     return new AbstractCollection() {
       // required impl
@@ -635,7 +661,9 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
     };
   }
 
-  // per Map.entrySet()
+  /**
+   *  Implements {@link Map#entrySet()}.
+   */
   public Set entrySet() {
     return new AbstractSet() {
       // helper
@@ -968,6 +996,14 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
   }
 
   // per Externalizable.readExternal(ObjectInput)
+
+  /**
+   *  Deserializes this map from the given stream.
+   *
+   *  @param in the stream to deserialize from
+   *  @throws IOException if the stream raises it
+   *  @throws ClassNotFoundException if the stream raises it
+   */
   public void readExternal( ObjectInput in ) 
     throws IOException, ClassNotFoundException 
   {
@@ -979,7 +1015,12 @@ public class SequencedHashMap implements Map, Cloneable, Externalizable {
     }
   }
   
-  // per Externalizable.writeExternal(ObjectOutput)
+  /**
+   *  Serializes this map to the given stream.
+   *
+   *  @param out  the stream to serialize to
+   *  @throws IOException  if the stream raises it
+   */
   public void writeExternal( ObjectOutput out ) throws IOException {
     out.writeInt(size());
     for(Entry pos = sentinel.next; pos != sentinel; pos = pos.next) {
diff --git a/src/java/org/apache/commons/collections/SingletonIterator.java b/src/java/org/apache/commons/collections/SingletonIterator.java
index 3429c6271..ba08b2064 100644
--- a/src/java/org/apache/commons/collections/SingletonIterator.java
+++ b/src/java/org/apache/commons/collections/SingletonIterator.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/SingletonIterator.java,v 1.5 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.5 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/SingletonIterator.java,v 1.6 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.6 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -68,21 +68,38 @@ import java.util.NoSuchElementException;
   *
   * @since 2.0
   * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
-  * @version $Revision: 1.5 $
+  * @version $Revision: 1.6 $
   */
 public class SingletonIterator implements Iterator {
 
     private boolean first = true;
     private Object object;
     
+    /**
+     *  Constructs a new <Code>SingletonIterator</Code>.
+     *
+     *  @param object  the single object to return from the iterator
+     */
     public SingletonIterator(Object object) {
         this.object = object;
     }
 
+    /**
+     *  Returns true if the single object hasn't been returned yet.
+     * 
+     *  @return true if the single object hasn't been returned yet
+     */
     public boolean hasNext() {
         return first;
     }
 
+    /**
+     *  Returns the single object if it hasn't been returned yet.
+     *
+     *  @return the single object
+     *  @throws NoSuchElementException if the single object has already been
+     *    returned
+     */
     public Object next() {
         if (! first ) {
             throw new NoSuchElementException();
@@ -93,6 +110,11 @@ public class SingletonIterator implements Iterator {
         return answer;
     }
 
+    /**
+     *  Throws {@link UnsupportedOperationException}.
+     *
+     *  @throws UnsupportedOperationException always
+     */
     public void remove() {
         throw new UnsupportedOperationException( "remove() is not supported by this iterator" );
     }
diff --git a/src/java/org/apache/commons/collections/StaticBucketMap.java b/src/java/org/apache/commons/collections/StaticBucketMap.java
index 9aa19a624..6483ddc9d 100644
--- a/src/java/org/apache/commons/collections/StaticBucketMap.java
+++ b/src/java/org/apache/commons/collections/StaticBucketMap.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/StaticBucketMap.java,v 1.3 2002/08/15 03:22:29 pjack Exp $
- * $Revision: 1.3 $
- * $Date: 2002/08/15 03:22:29 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/StaticBucketMap.java,v 1.4 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.4 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -137,7 +137,7 @@ import java.util.NoSuchElementException;
  * @author  <a href="mailto:g-froehlich@gmx.de">Gerhard Froehlich</a>
  * @author  <a href="mailto:mas@apache.org">Michael A. Smith</a>
  * @author  Paul Jack
- * @version CVS $Revision: 1.3 $ $Date: 2002/08/15 03:22:29 $
+ * @version CVS $Revision: 1.4 $ $Date: 2002/08/15 20:04:31 $
  * @since Avalon 4.0
  */
 public final class StaticBucketMap implements Map
@@ -211,7 +211,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     *  Returns a set view of this map's keys.
+     *  Implements {@link Map#keySet()}.
      */
     public Set keySet()
     {
@@ -219,7 +219,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     * Returns the current number of key, value pairs.
+     *  Implements {@link Map#size()}.
      */
     public int size()
     {
@@ -234,7 +234,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     * Put a reference in the Map.
+     *  Implements {@link Map#put(Object, Object)}.
      */
     public Object put( final Object key, final Object value )
     {
@@ -282,7 +282,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     * Get an object from the Map by the key
+     *  Implements {@link Map#get(Object)}.
      */
     public Object get( final Object key )
     {
@@ -307,7 +307,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     * Checks to see if the provided key exists in the Map.
+     * Implements {@link Map#containsKey(Object)}.
      */
     public boolean containsKey( final Object key )
     {
@@ -332,9 +332,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     * Checks to see if a value exists.  This operation crosses bucket
-     * boundaries, so it is less efficient, and greatly increases the chance
-     * for thread contention.
+     * Implements {@link Map#containsValue(Object)}.
      */
     public boolean containsValue( final Object value )
     {
@@ -361,9 +359,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     * Obtain a Set for the values.  This operation crosses bucket boundaries,
-     * so it is less efficient, and greatly increases the chance for thread
-     * contention.
+     *  Implements {@link Map#values()}.
      */
     public Collection values()
     {
@@ -371,9 +367,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     * Obtain a Set for the entries.  This operation crosses bucket boundaries,
-     * so it is less efficient, and greatly increases the chance for thread
-     * contention.
+     *  Implements {@link Map#entrySet()}.
      */
     public Set entrySet()
     {
@@ -381,7 +375,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     * Add all the contents of one Map into this one.
+     *  Implements {@link Map#putAll(Map)}.
      */
     public void putAll( Map other )
     {
@@ -395,7 +389,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     * Removes the object from the Map based on the key.
+     *  Implements {@link Map#remove(Object)}.
      */
     public Object remove( Object key )
     {
@@ -434,7 +428,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     * Tests if the Map is empty.
+     *  Implements {@link Map#isEmpty()}.
      */
     public final boolean isEmpty()
     {
@@ -442,7 +436,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     * Removes all the entries from the Map.
+     *  Implements {@link Map#clear()}.
      */
     public final void clear()
     {
@@ -457,11 +451,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     *  Returns true if the given object is a map with the same mappings
-     *  as this map.
-     *
-     *  @return true if the given object is the a map with same mappings
-     *   as this map
+     *  Implements {@link Map#equals(Object)}.
      */
     public final boolean equals( Object obj )
     {
@@ -476,9 +466,7 @@ public final class StaticBucketMap implements Map
     }
 
     /**
-     *  Returns a hash code for this map.
-     *
-     *  @return a hash code for this map
+     *  Implements {@link Map#hashCode()}.
      */
     public final int hashCode() 
     {
diff --git a/src/java/org/apache/commons/collections/SynchronizedPriorityQueue.java b/src/java/org/apache/commons/collections/SynchronizedPriorityQueue.java
index 4fdab6f1b..d1e79c11e 100644
--- a/src/java/org/apache/commons/collections/SynchronizedPriorityQueue.java
+++ b/src/java/org/apache/commons/collections/SynchronizedPriorityQueue.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/SynchronizedPriorityQueue.java,v 1.4 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.4 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/SynchronizedPriorityQueue.java,v 1.5 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.5 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -73,8 +73,18 @@ import java.util.NoSuchElementException;
 public final class SynchronizedPriorityQueue 
     implements PriorityQueue
 {
+
+    /**
+     *  The underlying priority queue.
+     */
     protected final PriorityQueue   m_priorityQueue;
 
+
+    /**
+     *  Constructs a new synchronized priority queue.
+     *
+     *  @param priorityQueue the priority queue to synchronize
+     */
     public SynchronizedPriorityQueue( final PriorityQueue priorityQueue )
     {
         m_priorityQueue = priorityQueue;
@@ -130,6 +140,11 @@ public final class SynchronizedPriorityQueue
         return m_priorityQueue.pop();
     }
 
+    /**
+     *  Returns a string representation of the underlying queue.
+     *
+     *  @return a string representation of the underlying queue
+     */
     public synchronized String toString()
     {
         return m_priorityQueue.toString();
diff --git a/src/java/org/apache/commons/collections/TransformIterator.java b/src/java/org/apache/commons/collections/TransformIterator.java
index 61d1c69c5..7f192c977 100644
--- a/src/java/org/apache/commons/collections/TransformIterator.java
+++ b/src/java/org/apache/commons/collections/TransformIterator.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/TransformIterator.java,v 1.4 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.4 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/TransformIterator.java,v 1.5 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.5 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -76,13 +76,32 @@ public class TransformIterator extends ProxyIterator {
     private Transformer transformer;
     
     
+    /**
+     *  Constructs a new <Code>TransformIterator</Code> that will not function
+     *  until the {@link #setIterator(Iterator) setIterator} method is 
+     *  invoked.
+     */
     public TransformIterator() {
     }
     
+    /**
+     *  Constructs a new <Code>TransformIterator</Code> that won't transform
+     *  elements from the given iterator.
+     *
+     *  @param iterator  the iterator to use
+     */
     public TransformIterator( Iterator iterator ) {
         super( iterator );
     }
 
+    /**
+     *  Constructs a new <Code>TransformIterator</Code> that will use the
+     *  given iterator and transformer.  If the given transformer is null,
+     *  then objects will not be transformed.
+     *
+     *  @param iterator  the iterator to use
+     *  @param transformer  the transformer to use
+     */
     public TransformIterator( Iterator iterator, Transformer transformer ) {
         super( iterator );
         this.transformer = transformer;
@@ -111,6 +130,14 @@ public class TransformIterator extends ProxyIterator {
     
     // Implementation methods
     //-------------------------------------------------------------------------
+
+    /**
+     *  Transforms the given object using the transformer.  If the 
+     *  transformer is null, the original object is returned as-is.
+     *
+     *  @param source  the object to transform
+     *  @return  the transformed object
+     */
     protected Object transform( Object source ) {
         Transformer transformer = getTransformer();
         if ( transformer != null ) {
diff --git a/src/java/org/apache/commons/collections/TreeBag.java b/src/java/org/apache/commons/collections/TreeBag.java
index bc1d9342a..55db0fd3a 100644
--- a/src/java/org/apache/commons/collections/TreeBag.java
+++ b/src/java/org/apache/commons/collections/TreeBag.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/TreeBag.java,v 1.5 2002/06/12 03:59:15 mas Exp $
- * $Revision: 1.5 $
- * $Date: 2002/06/12 03:59:15 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/TreeBag.java,v 1.6 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.6 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -75,6 +75,10 @@ import java.util.TreeMap;
  * @author Chuck Burdick
  **/
 public class TreeBag extends DefaultMapBag implements SortedBag, Bag {
+
+   /**
+    *  Constructs a new empty <Code>TreeBag</Code>.
+    */
    public TreeBag() {
       setMap(new TreeMap());
    }
diff --git a/src/java/org/apache/commons/collections/UniqueFilterIterator.java b/src/java/org/apache/commons/collections/UniqueFilterIterator.java
index fd145a2b3..02ff43535 100644
--- a/src/java/org/apache/commons/collections/UniqueFilterIterator.java
+++ b/src/java/org/apache/commons/collections/UniqueFilterIterator.java
@@ -1,7 +1,7 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/UniqueFilterIterator.java,v 1.2 2002/08/13 00:46:25 pjack Exp $
- * $Revision: 1.2 $
- * $Date: 2002/08/13 00:46:25 $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Attic/UniqueFilterIterator.java,v 1.3 2002/08/15 20:04:31 pjack Exp $
+ * $Revision: 1.3 $
+ * $Date: 2002/08/15 20:04:31 $
  *
  * ====================================================================
  *
@@ -69,7 +69,7 @@ import java.util.NoSuchElementException;
   * and duplicate Objects are skipped.
   *
   * @author Morgan Delagrange
-  * @version $Id: UniqueFilterIterator.java,v 1.2 2002/08/13 00:46:25 pjack Exp $
+  * @version $Id: UniqueFilterIterator.java,v 1.3 2002/08/15 20:04:31 pjack Exp $
   * @since 2.1
   */
 
@@ -77,6 +77,11 @@ public class UniqueFilterIterator extends FilterIterator {
        
     //-------------------------------------------------------------------------
     
+    /**
+     *  Constructs a new <Code>UniqueFilterIterator</Code>.
+     *
+     *  @param iterator  the iterator to use
+     */
     public UniqueFilterIterator( Iterator iterator ) {
         super( iterator, new UniquePredicate() );
     }