From b8bb52254dbeebca3f950df1fbc38a10e86fb3ed Mon Sep 17 00:00:00 2001
From: Stephen Colebourne <scolebourne@apache.org>
Date: Sun, 28 Dec 2003 14:55:46 +0000
Subject: [PATCH] Improve documentation

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@131461 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/commons/collections/bag/HashBag.java    | 10 ++++++++--
 .../commons/collections/bag/SynchronizedBag.java       |  5 +++--
 .../commons/collections/bag/SynchronizedSortedBag.java |  5 +++--
 .../org/apache/commons/collections/bag/TreeBag.java    | 10 ++++++++--
 4 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/src/java/org/apache/commons/collections/bag/HashBag.java b/src/java/org/apache/commons/collections/bag/HashBag.java
index 087df0dcb..f2d54f968 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.2 2003/12/03 00:49:38 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.3 2003/12/28 14:55:46 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -69,9 +69,15 @@ import org.apache.commons.collections.Bag;
 /**
  * Implements <code>Bag</code>, using a <code>HashMap</code> to provide the
  * data storage. This is the standard implementation of a bag.
+ * <p>
+ * A <code>Bag</code> stores each object in the collection together with a
+ * count of occurances. Extra methods on the interface allow multiple copies
+ * of an object to be added or removed at once. It is important to read the
+ * interface javadoc carefully as several methods violate the
+ * <code>Collection</code> interface specification.
  *
  * @since Commons Collections 3.0
- * @version $Revision: 1.2 $ $Date: 2003/12/03 00:49:38 $
+ * @version $Revision: 1.3 $ $Date: 2003/12/28 14:55:46 $
  * 
  * @author Chuck Burdick
  * @author Stephen Colebourne
diff --git a/src/java/org/apache/commons/collections/bag/SynchronizedBag.java b/src/java/org/apache/commons/collections/bag/SynchronizedBag.java
index ac9eddebe..89df78f1f 100644
--- a/src/java/org/apache/commons/collections/bag/SynchronizedBag.java
+++ b/src/java/org/apache/commons/collections/bag/SynchronizedBag.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/SynchronizedBag.java,v 1.1 2003/11/16 00:05:43 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/bag/SynchronizedBag.java,v 1.2 2003/12/28 14:55:46 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -68,9 +68,10 @@ import org.apache.commons.collections.set.SynchronizedSet;
  * for a multi-threaded environment.
  * <p>
  * Methods are synchronized, then forwarded to the decorated bag.
+ * Iterators must be separately synchronized around the loop.
  *
  * @since Commons Collections 3.0
- * @version $Revision: 1.1 $ $Date: 2003/11/16 00:05:43 $
+ * @version $Revision: 1.2 $ $Date: 2003/12/28 14:55:46 $
  * 
  * @author Stephen Colebourne
  */
diff --git a/src/java/org/apache/commons/collections/bag/SynchronizedSortedBag.java b/src/java/org/apache/commons/collections/bag/SynchronizedSortedBag.java
index e565284c1..8b686edaa 100644
--- a/src/java/org/apache/commons/collections/bag/SynchronizedSortedBag.java
+++ b/src/java/org/apache/commons/collections/bag/SynchronizedSortedBag.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/SynchronizedSortedBag.java,v 1.1 2003/11/16 00:05:43 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/bag/SynchronizedSortedBag.java,v 1.2 2003/12/28 14:55:46 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -67,9 +67,10 @@ import org.apache.commons.collections.SortedBag;
  * for a multi-threaded environment.
  * <p>
  * Methods are synchronized, then forwarded to the decorated bag.
+ * Iterators must be separately synchronized around the loop.
  *
  * @since Commons Collections 3.0
- * @version $Revision: 1.1 $ $Date: 2003/11/16 00:05:43 $
+ * @version $Revision: 1.2 $ $Date: 2003/12/28 14:55:46 $
  * 
  * @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 07f8334ba..1a2305c00 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.2 2003/12/03 00:49:38 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.3 2003/12/28 14:55:46 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -74,9 +74,15 @@ import org.apache.commons.collections.SortedBag;
  * <p>
  * Order will be maintained among the bag members and can be viewed through the
  * iterator.
+ * <p>
+ * A <code>Bag</code> stores each object in the collection together with a
+ * count of occurances. Extra methods on the interface allow multiple copies
+ * of an object to be added or removed at once. It is important to read the
+ * interface javadoc carefully as several methods violate the
+ * <code>Collection</code> interface specification.
  *
  * @since Commons Collections 3.0
- * @version $Revision: 1.2 $ $Date: 2003/12/03 00:49:38 $
+ * @version $Revision: 1.3 $ $Date: 2003/12/28 14:55:46 $
  * 
  * @author Chuck Burdick
  * @author Stephen Colebourne