Improve documentation

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

src/java/org/apache/commons/collections/HashBag.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/HashBag.java,v 1.10 2003/12/02 23:36:12 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/HashBag.java,v 1.11 2003/12/28 16:36:48 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -63,9 +63,9 @@ import java.util.HashMap;
 /**
  * A {@link Bag} that is backed by a {@link HashMap}.
  *
- * @deprecated Moved to bag subpackage. Due to be removed in v4.0.
+ * @deprecated Moved to bag subpackage and rewritten internally. Due to be removed in v4.0.
  * @since Commons Collections 2.0
- * @version $Revision: 1.10 $ $Date: 2003/12/02 23:36:12 $
+ * @version $Revision: 1.11 $ $Date: 2003/12/28 16:36:48 $
  * 
  * @author Chuck Burdick
  */

src/java/org/apache/commons/collections/TreeBag.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/TreeBag.java,v 1.10 2003/12/02 23:36:12 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/TreeBag.java,v 1.11 2003/12/28 16:36:48 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -67,9 +67,9 @@ import java.util.TreeMap;
  * Order will be maintained among the unique representative
  * members.
  *
- * @deprecated Moved to bag subpackage. Due to be removed in v4.0.
+ * @deprecated Moved to bag subpackage and rewritten internally. Due to be removed in v4.0.
  * @since Commons Collections 2.0
- * @version $Revision: 1.10 $ $Date: 2003/12/02 23:36:12 $
+ * @version $Revision: 1.11 $ $Date: 2003/12/28 16:36:48 $
  * 
  * @author Chuck Burdick
  */

src/java/org/apache/commons/collections/bag/AbstractMapBag.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/bag/AbstractMapBag.java,v 1.8 2003/12/28 14:46:28 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/bag/AbstractMapBag.java,v 1.9 2003/12/28 16:36:48 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -78,8 +78,8 @@ import org.apache.commons.collections.set.UnmodifiableSet;
  * 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.
  *
- * @since Commons Collections 3.0
+ * @since Commons Collections 3.0 (previously DefaultMapBag v2.0)
- * @version $Revision: 1.8 $ $Date: 2003/12/28 14:46:28 $
+ * @version $Revision: 1.9 $ $Date: 2003/12/28 16:36:48 $
  * 
  * @author Chuck Burdick
  * @author Michael A. Smith

src/java/org/apache/commons/collections/bag/HashBag.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/bag/HashBag.java,v 1.3 2003/12/28 14:55:46 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/bag/HashBag.java,v 1.4 2003/12/28 16:36:48 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -76,8 +76,8 @@ import org.apache.commons.collections.Bag;
  * interface javadoc carefully as several methods violate the
  * <code>Collection</code> interface specification.
  *
- * @since Commons Collections 3.0
+ * @since Commons Collections 3.0 (previously in main package v2.0)
- * @version $Revision: 1.3 $ $Date: 2003/12/28 14:55:46 $
+ * @version $Revision: 1.4 $ $Date: 2003/12/28 16:36:48 $
  * 
  * @author Chuck Burdick
  * @author Stephen Colebourne

src/java/org/apache/commons/collections/bag/TreeBag.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/bag/TreeBag.java,v 1.3 2003/12/28 14:55:46 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/bag/TreeBag.java,v 1.4 2003/12/28 16:36:48 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -81,8 +81,8 @@ import org.apache.commons.collections.SortedBag;
  * interface javadoc carefully as several methods violate the
  * <code>Collection</code> interface specification.
  *
- * @since Commons Collections 3.0
+ * @since Commons Collections 3.0 (previously in main package v2.0)
- * @version $Revision: 1.3 $ $Date: 2003/12/28 14:55:46 $
+ * @version $Revision: 1.4 $ $Date: 2003/12/28 16:36:48 $
  * 
  * @author Chuck Burdick
  * @author Stephen Colebourne

src/java/org/apache/commons/collections/buffer/BinaryHeap.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/buffer/Attic/BinaryHeap.java,v 1.1 2003/11/29 18:04:57 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/buffer/Attic/BinaryHeap.java,v 1.2 2003/12/28 16:36:48 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -90,8 +90,8 @@ import org.apache.commons.collections.PriorityQueue;
  * Buffer heap = BufferUtils.synchronizedBuffer(new BinaryHeap());
  * </pre>
  *
- * @since Commons Collections 3.0
+ * @since Commons Collections 3.0 (previously in main package v1.0)
- * @version $Revision: 1.1 $ $Date: 2003/11/29 18:04:57 $
+ * @version $Revision: 1.2 $ $Date: 2003/12/28 16:36:48 $
  * 
  * @author Peter Donald
  * @author Ram Chidambaram

src/java/org/apache/commons/collections/buffer/BoundedFifoBuffer.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/buffer/BoundedFifoBuffer.java,v 1.2 2003/11/29 18:14:20 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/buffer/BoundedFifoBuffer.java,v 1.3 2003/12/28 16:36:48 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -88,8 +88,8 @@ import org.apache.commons.collections.BufferUnderflowException;
  * <p>
  * This buffer prevents null objects from being added.
  *
- * @since Commons Collections 3.0
+ * @since Commons Collections 3.0 (previously in main package v2.1)
- * @version $Revision: 1.2 $ $Date: 2003/11/29 18:14:20 $
+ * @version $Revision: 1.3 $ $Date: 2003/12/28 16:36:48 $
  * 
  * @author Avalon
  * @author Berin Loritsch

src/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java,v 1.1 2003/11/29 18:04:57 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java,v 1.2 2003/12/28 16:36:48 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -85,8 +85,8 @@ import org.apache.commons.collections.BufferUnderflowException;
  * <p>
  * This buffer prevents null objects from being added.
  * 
- * @since Commons Collections 3.0
+ * @since Commons Collections 3.0 (previously in main package v2.1)
- * @version $Revision: 1.1 $ $Date: 2003/11/29 18:04:57 $
+ * @version $Revision: 1.2 $ $Date: 2003/12/28 16:36:48 $
  *
  * @author Avalon
  * @author Federico Barbieri

src/java/org/apache/commons/collections/map/HashedMap.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/map/HashedMap.java,v 1.9 2003/12/07 23:59:13 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/map/HashedMap.java,v 1.10 2003/12/28 16:36:48 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -64,15 +64,15 @@ import java.io.Serializable;
 import java.util.Map;
 
 /**
- * A <code>Map</code> implementation that is a general purpose replacement
+ * A <code>Map</code> implementation that is a general purpose alternative
- * for <code>HashMap</code>.
+ * to <code>HashMap</code>.
  * <p>
  * This implementation improves on the JDK1.4 HahMap by adding the 
  * {@link org.apache.commons.collections.iterators.MapIterator MapIterator}
- * functionality and improving performance of <code>putAll</code>.
+ * functionality and many methods for subclassing.
  * <p>
  * @since Commons Collections 3.0
- * @version $Revision: 1.9 $ $Date: 2003/12/07 23:59:13 $
+ * @version $Revision: 1.10 $ $Date: 2003/12/28 16:36:48 $
  *
  * @author Stephen Colebourne
  */

src/java/org/apache/commons/collections/map/ReferenceMap.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/map/ReferenceMap.java,v 1.3 2003/12/06 13:03:15 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/map/ReferenceMap.java,v 1.4 2003/12/28 16:36:48 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -80,46 +80,46 @@ import org.apache.commons.collections.KeyValue;
 import org.apache.commons.collections.keyvalue.DefaultMapEntry;
 
 /**
- *  Hash-based {@link Map} implementation that allows
+ * Hash-based <code>Map</code> implementation that allows
- *  mappings to be removed by the garbage collector.<p>
+ * mappings to be removed by the garbage collector.
- *
+ * <p>
- *  When you construct a <code>ReferenceMap</code>, you can 
+ * When you construct a <code>ReferenceMap</code>, you can 
- *  specify what kind of references are used to store the
+ * specify what kind of references are used to store the
- *  map's keys and values.  If non-hard references are 
+ * map's keys and values.  If non-hard references are 
- *  used, then the garbage collector can remove mappings
+ * used, then the garbage collector can remove mappings
- *  if a key or value becomes unreachable, or if the 
+ * if a key or value becomes unreachable, or if the 
- *  JVM's memory is running low.  For information on how
+ * JVM's memory is running low.  For information on how
- *  the different reference types behave, see
+ * the different reference types behave, see
- *  {@link Reference}.<p>
+ * {@link Reference}.
- *
+ * <p>
- *  Different types of references can be specified for keys
+ * Different types of references can be specified for keys
- *  and values.  The keys can be configured to be weak but
+ * and values.  The keys can be configured to be weak but
- *  the values hard, in which case this class will behave
+ * the values hard, in which case this class will behave
- *  like a <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/WeakHashMap.html">
+ * like a <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/WeakHashMap.html">
- *  <code>WeakHashMap</code></a>.  However, you
+ * <code>WeakHashMap</code></a>.  However, you
- *  can also specify hard keys and weak values, or any other
+ * can also specify hard keys and weak values, or any other
- *  combination.  The default constructor uses hard keys
+ * combination.  The default constructor uses hard keys
- *  and soft values, providing a memory-sensitive cache.<p>
+ * and soft values, providing a memory-sensitive cache.
- *
+ * <p>
- *  The algorithms used are basically the same as those
+ * The algorithms used are basically the same as those
- *  in {@link java.util.HashMap}.  In particular, you 
+ * in {@link java.util.HashMap}.  In particular, you 
- *  can specify a load factor and capacity to suit your
+ * can specify a load factor and capacity to suit your
- *  needs.  All optional {@link Map} operations are 
+ * needs.  All optional {@link Map} operations are 
- *  supported.<p>
+ * supported.
- *
+ * <p>
- *  However, this {@link Map} implementation does <I>not</I>
+ * However, this {@link Map} implementation does <I>not</I>
- *  allow null elements.  Attempting to add a null key or
+ * allow null elements.  Attempting to add a null key or
- *  or a null value to the map will raise a 
+ * or a null value to the map will raise a 
- *  <code>NullPointerException</code>.<p>
+ * <code>NullPointerException</code>.
- *
+ * <p>
- *  As usual, this implementation is not synchronized.  You
+ * As usual, this implementation is not synchronized.  You
- *  can use {@link java.util.Collections#synchronizedMap} to 
+ * can use {@link java.util.Collections#synchronizedMap} to 
- *  provide synchronized access to a <code>ReferenceMap</code>.
+ * provide synchronized access to a <code>ReferenceMap</code>.
  *
  * @see java.lang.ref.Reference
  * 
- * @since Commons Collections 3.0
+ * @since Commons Collections 3.0 (previously in main package v2.1)
- * @version $Revision: 1.3 $ $Date: 2003/12/06 13:03:15 $
+ * @version $Revision: 1.4 $ $Date: 2003/12/28 16:36:48 $
  * 
  * @author Paul Jack
  */

src/java/org/apache/commons/collections/map/StaticBucketMap.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/map/StaticBucketMap.java,v 1.3 2003/12/14 13:00:03 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/map/StaticBucketMap.java,v 1.4 2003/12/28 16:36:48 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -131,8 +131,8 @@ import org.apache.commons.collections.KeyValue;
  * iterations, or if you can make your own guarantees about how bulk 
  * operations will affect the map.<p>
  *
- * @since Commons Collections 3.0
+ * @since Commons Collections 3.0 (previously in main package v2.1)
- * @version $Revision: 1.3 $ $Date: 2003/12/14 13:00:03 $
+ * @version $Revision: 1.4 $ $Date: 2003/12/28 16:36:48 $
  * 
  * @author Berin Loritsch
  * @author Gerhard Froehlich