From ac7b2ec52721ca43b66b38592af926fe6064e78a Mon Sep 17 00:00:00 2001 From: Stephen Colebourne Date: Sun, 28 Dec 2003 16:36:48 +0000 Subject: [PATCH] Improve documentation git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@131462 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/commons/collections/HashBag.java | 6 +- .../apache/commons/collections/TreeBag.java | 6 +- .../collections/bag/AbstractMapBag.java | 6 +- .../commons/collections/bag/HashBag.java | 6 +- .../commons/collections/bag/TreeBag.java | 6 +- .../collections/buffer/BinaryHeap.java | 6 +- .../collections/buffer/BoundedFifoBuffer.java | 6 +- .../buffer/UnboundedFifoBuffer.java | 6 +- .../commons/collections/map/HashedMap.java | 10 +-- .../commons/collections/map/ReferenceMap.java | 76 +++++++++---------- .../collections/map/StaticBucketMap.java | 6 +- 11 files changed, 70 insertions(+), 70 deletions(-) diff --git a/src/java/org/apache/commons/collections/HashBag.java b/src/java/org/apache/commons/collections/HashBag.java index 2310b8f2f..d3deedd13 100644 --- a/src/java/org/apache/commons/collections/HashBag.java +++ b/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 */ diff --git a/src/java/org/apache/commons/collections/TreeBag.java b/src/java/org/apache/commons/collections/TreeBag.java index d008b12a2..e32731cb2 100644 --- a/src/java/org/apache/commons/collections/TreeBag.java +++ b/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 */ diff --git a/src/java/org/apache/commons/collections/bag/AbstractMapBag.java b/src/java/org/apache/commons/collections/bag/AbstractMapBag.java index 33ec77941..30ead0341 100644 --- a/src/java/org/apache/commons/collections/bag/AbstractMapBag.java +++ b/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 - * @version $Revision: 1.8 $ $Date: 2003/12/28 14:46:28 $ + * @since Commons Collections 3.0 (previously DefaultMapBag v2.0) + * @version $Revision: 1.9 $ $Date: 2003/12/28 16:36:48 $ * * @author Chuck Burdick * @author Michael A. Smith diff --git a/src/java/org/apache/commons/collections/bag/HashBag.java b/src/java/org/apache/commons/collections/bag/HashBag.java index f2d54f968..ad3bd16cf 100644 --- a/src/java/org/apache/commons/collections/bag/HashBag.java +++ b/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 * Collection interface specification. * - * @since Commons Collections 3.0 - * @version $Revision: 1.3 $ $Date: 2003/12/28 14:55:46 $ + * @since Commons Collections 3.0 (previously in main package v2.0) + * @version $Revision: 1.4 $ $Date: 2003/12/28 16:36:48 $ * * @author Chuck Burdick * @author Stephen Colebourne diff --git a/src/java/org/apache/commons/collections/bag/TreeBag.java b/src/java/org/apache/commons/collections/bag/TreeBag.java index 1a2305c00..589440a9a 100644 --- a/src/java/org/apache/commons/collections/bag/TreeBag.java +++ b/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 * Collection interface specification. * - * @since Commons Collections 3.0 - * @version $Revision: 1.3 $ $Date: 2003/12/28 14:55:46 $ + * @since Commons Collections 3.0 (previously in main package v2.0) + * @version $Revision: 1.4 $ $Date: 2003/12/28 16:36:48 $ * * @author Chuck Burdick * @author Stephen Colebourne diff --git a/src/java/org/apache/commons/collections/buffer/BinaryHeap.java b/src/java/org/apache/commons/collections/buffer/BinaryHeap.java index ac68573bb..b988e3375 100644 --- a/src/java/org/apache/commons/collections/buffer/BinaryHeap.java +++ b/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()); * * - * @since Commons Collections 3.0 - * @version $Revision: 1.1 $ $Date: 2003/11/29 18:04:57 $ + * @since Commons Collections 3.0 (previously in main package v1.0) + * @version $Revision: 1.2 $ $Date: 2003/12/28 16:36:48 $ * * @author Peter Donald * @author Ram Chidambaram diff --git a/src/java/org/apache/commons/collections/buffer/BoundedFifoBuffer.java b/src/java/org/apache/commons/collections/buffer/BoundedFifoBuffer.java index ac63ec722..54b4774c4 100644 --- a/src/java/org/apache/commons/collections/buffer/BoundedFifoBuffer.java +++ b/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; *

* This buffer prevents null objects from being added. * - * @since Commons Collections 3.0 - * @version $Revision: 1.2 $ $Date: 2003/11/29 18:14:20 $ + * @since Commons Collections 3.0 (previously in main package v2.1) + * @version $Revision: 1.3 $ $Date: 2003/12/28 16:36:48 $ * * @author Avalon * @author Berin Loritsch diff --git a/src/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java b/src/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java index a31d98828..0f70a567a 100644 --- a/src/java/org/apache/commons/collections/buffer/UnboundedFifoBuffer.java +++ b/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; *

* This buffer prevents null objects from being added. * - * @since Commons Collections 3.0 - * @version $Revision: 1.1 $ $Date: 2003/11/29 18:04:57 $ + * @since Commons Collections 3.0 (previously in main package v2.1) + * @version $Revision: 1.2 $ $Date: 2003/12/28 16:36:48 $ * * @author Avalon * @author Federico Barbieri diff --git a/src/java/org/apache/commons/collections/map/HashedMap.java b/src/java/org/apache/commons/collections/map/HashedMap.java index 29262e5da..b08157fb7 100644 --- a/src/java/org/apache/commons/collections/map/HashedMap.java +++ b/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 Map implementation that is a general purpose replacement - * for HashMap. + * A Map implementation that is a general purpose alternative + * to HashMap. *

* This implementation improves on the JDK1.4 HahMap by adding the * {@link org.apache.commons.collections.iterators.MapIterator MapIterator} - * functionality and improving performance of putAll. + * functionality and many methods for subclassing. *

* @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 */ diff --git a/src/java/org/apache/commons/collections/map/ReferenceMap.java b/src/java/org/apache/commons/collections/map/ReferenceMap.java index 68ede4d32..89af944ae 100644 --- a/src/java/org/apache/commons/collections/map/ReferenceMap.java +++ b/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 - * mappings to be removed by the garbage collector.

- * - * When you construct a ReferenceMap, you can - * specify what kind of references are used to store the - * map's keys and values. If non-hard references are - * used, then the garbage collector can remove mappings - * if a key or value becomes unreachable, or if the - * JVM's memory is running low. For information on how - * the different reference types behave, see - * {@link Reference}.

- * - * Different types of references can be specified for keys - * and values. The keys can be configured to be weak but - * the values hard, in which case this class will behave - * like a - * WeakHashMap. However, you - * can also specify hard keys and weak values, or any other - * combination. The default constructor uses hard keys - * and soft values, providing a memory-sensitive cache.

- * - * The algorithms used are basically the same as those - * in {@link java.util.HashMap}. In particular, you - * can specify a load factor and capacity to suit your - * needs. All optional {@link Map} operations are - * supported.

- * - * However, this {@link Map} implementation does not - * allow null elements. Attempting to add a null key or - * or a null value to the map will raise a - * NullPointerException.

- * - * As usual, this implementation is not synchronized. You - * can use {@link java.util.Collections#synchronizedMap} to - * provide synchronized access to a ReferenceMap. + * Hash-based Map implementation that allows + * mappings to be removed by the garbage collector. + *

+ * When you construct a ReferenceMap, you can + * specify what kind of references are used to store the + * map's keys and values. If non-hard references are + * used, then the garbage collector can remove mappings + * if a key or value becomes unreachable, or if the + * JVM's memory is running low. For information on how + * the different reference types behave, see + * {@link Reference}. + *

+ * Different types of references can be specified for keys + * and values. The keys can be configured to be weak but + * the values hard, in which case this class will behave + * like a + * WeakHashMap. However, you + * can also specify hard keys and weak values, or any other + * combination. The default constructor uses hard keys + * and soft values, providing a memory-sensitive cache. + *

+ * The algorithms used are basically the same as those + * in {@link java.util.HashMap}. In particular, you + * can specify a load factor and capacity to suit your + * needs. All optional {@link Map} operations are + * supported. + *

+ * However, this {@link Map} implementation does not + * allow null elements. Attempting to add a null key or + * or a null value to the map will raise a + * NullPointerException. + *

+ * As usual, this implementation is not synchronized. You + * can use {@link java.util.Collections#synchronizedMap} to + * provide synchronized access to a ReferenceMap. * * @see java.lang.ref.Reference * - * @since Commons Collections 3.0 - * @version $Revision: 1.3 $ $Date: 2003/12/06 13:03:15 $ + * @since Commons Collections 3.0 (previously in main package v2.1) + * @version $Revision: 1.4 $ $Date: 2003/12/28 16:36:48 $ * * @author Paul Jack */ diff --git a/src/java/org/apache/commons/collections/map/StaticBucketMap.java b/src/java/org/apache/commons/collections/map/StaticBucketMap.java index 6b8e834d8..9f8071578 100644 --- a/src/java/org/apache/commons/collections/map/StaticBucketMap.java +++ b/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.

* - * @since Commons Collections 3.0 - * @version $Revision: 1.3 $ $Date: 2003/12/14 13:00:03 $ + * @since Commons Collections 3.0 (previously in main package v2.1) + * @version $Revision: 1.4 $ $Date: 2003/12/28 16:36:48 $ * * @author Berin Loritsch * @author Gerhard Froehlich