[COLLECTIONS-231] return specific type rather than base type in factory methods, javadoc cleanup.

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

src/main/java/org/apache/commons/collections/bag/AbstractBagDecorator.java

@@ -24,7 +24,7 @@ import org.apache.commons.collections.collection.AbstractCollectionDecorator;
 /**
  * Decorates another <code>Bag</code> to provide additional behaviour.
  * <p>
- * Methods are forwarded directly to the decorated bag.
+ * Methods are forwarded directly to the decorated bag.</p>
  *
  * @since Commons Collections 3.0
  * @version $Revision$
@@ -66,18 +66,31 @@ public abstract class AbstractBagDecorator<E>
     }
 
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public int getCount(Object object) {
         return decorated().getCount(object);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public boolean add(E object, int count) {
         return decorated().add(object, count);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public boolean remove(Object object, int count) {
         return decorated().remove(object, count);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public Set<E> uniqueSet() {
         return decorated().uniqueSet();
     }

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

@@ -35,7 +35,7 @@ import org.apache.commons.collections.set.UnmodifiableSet;
  * <p>
  * Subclasses specify a Map implementation to use as the internal storage. 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.
+ * number of occurrences of that element in the bag.</p>
  *
  * @since Commons Collections 3.0 (previously DefaultMapBag v2.0)
  * @version $Revision$

src/main/java/org/apache/commons/collections/bag/AbstractSortedBagDecorator.java

@@ -23,7 +23,7 @@ import org.apache.commons.collections.SortedBag;
 /**
  * Decorates another <code>SortedBag</code> to provide additional behaviour.
  * <p>
- * Methods are forwarded directly to the decorated bag.
+ * Methods are forwarded directly to the decorated bag.</p>
  *
  * @since Commons Collections 3.0
  * @version $Revision$

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

@@ -33,7 +33,7 @@ import org.apache.commons.collections.Bag;
  * count of occurrences. 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.
+ * <code>Collection</code> interface specification.</p>
  *
  * @since Commons Collections 3.0 (previously in main package v2.0)
  * @version $Revision$

src/main/java/org/apache/commons/collections/bag/PredicatedBag.java

@@ -28,12 +28,12 @@ import org.apache.commons.collections.collection.PredicatedCollection;
  * <p>
  * This bag exists to provide validation for the decorated bag.
  * It is normally created to decorate an empty bag.
- * If an object cannot be added to the bag, an IllegalArgumentException is thrown.
+ * If an object cannot be added to the bag, an IllegalArgumentException is thrown.</p>
  * <p>
  * One usage would be to ensure that no null entries are added to the bag.
- * <pre>Bag bag = PredicatedBag.decorate(new HashBag(), NotNullPredicate.INSTANCE);</pre>
+ * <pre>Bag bag = PredicatedBag.decorate(new HashBag(), NotNullPredicate.INSTANCE);</pre></p>
  * <p>
- * This class is Serializable from Commons Collections 3.1.
+ * This class is Serializable from Commons Collections 3.1.</p>
  *
  * @since Commons Collections 3.0
  * @version $Revision$
@@ -51,16 +51,17 @@ public class PredicatedBag<E>
      * Factory method to create a predicated (validating) bag.
      * <p>
      * If there are any elements already in the bag being decorated, they
-     * are validated.
+     * are validated.</p>
      * 
+     * @param <E> the type of the elements in the bag
      * @param bag  the bag to decorate, must not be null
      * @param predicate  the predicate to use for validation, must not be null
      * @return a new predicated Bag
      * @throws IllegalArgumentException if bag or predicate is null
      * @throws IllegalArgumentException if the bag contains invalid elements
      */
-    public static <T> Bag<T> predicatedBag(Bag<T> bag, Predicate<? super T> predicate) {
+    public static <E> PredicatedBag<E> predicatedBag(Bag<E> bag, Predicate<? super E> predicate) {
-        return new PredicatedBag<T>(bag, predicate);
+        return new PredicatedBag<E>(bag, predicate);
     }
 
     //-----------------------------------------------------------------------
@@ -68,7 +69,7 @@ public class PredicatedBag<E>
      * Constructor that wraps (not copies).
      * <p>
      * If there are any elements already in the bag being decorated, they
-     * are validated.
+     * are validated.</p>
      * 
      * @param bag  the bag to decorate, must not be null
      * @param predicate  the predicate to use for validation, must not be null
@@ -90,19 +91,32 @@ public class PredicatedBag<E>
     }
     
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public boolean add(E object, int count) {
         validate(object);
         return decorated().add(object, count);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public boolean remove(Object object, int count) {
         return decorated().remove(object, count);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public Set<E> uniqueSet() {
         return decorated().uniqueSet();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public int getCount(Object object) {
         return decorated().getCount(object);
     }

src/main/java/org/apache/commons/collections/bag/PredicatedSortedBag.java

@@ -27,12 +27,12 @@ import org.apache.commons.collections.SortedBag;
  * <p>
  * This bag exists to provide validation for the decorated bag.
  * It is normally created to decorate an empty bag.
- * If an object cannot be added to the bag, an IllegalArgumentException is thrown.
+ * If an object cannot be added to the bag, an IllegalArgumentException is thrown.</p>
  * <p>
  * One usage would be to ensure that no null entries are added to the bag.
- * <pre>SortedBag bag = PredicatedSortedBag.decorate(new TreeBag(), NotNullPredicate.INSTANCE);</pre>
+ * <pre>SortedBag bag = PredicatedSortedBag.decorate(new TreeBag(), NotNullPredicate.INSTANCE);</pre></p>
  * <p>
- * This class is Serializable from Commons Collections 3.1.
+ * This class is Serializable from Commons Collections 3.1.</p>
  *
  * @since Commons Collections 3.0
  * @version $Revision$
@@ -50,24 +50,24 @@ public class PredicatedSortedBag<E>
      * Factory method to create a predicated (validating) bag.
      * <p>
      * If there are any elements already in the bag being decorated, they
-     * are validated.
+     * are validated.</p>
      * 
+     * @param <E> the type of the elements in the bag
      * @param bag  the bag to decorate, must not be null
      * @param predicate  the predicate to use for validation, must not be null
      * @return a new predicated SortedBag
      * @throws IllegalArgumentException if bag or predicate is null
      * @throws IllegalArgumentException if the bag contains invalid elements
      */
-    public static <T> SortedBag<T> predicatedSortedBag(SortedBag<T> bag, Predicate<? super T> predicate) {
+    public static <E> PredicatedSortedBag<E> predicatedSortedBag(SortedBag<E> bag, Predicate<? super E> predicate) {
-        return new PredicatedSortedBag<T>(bag, predicate);
+        return new PredicatedSortedBag<E>(bag, predicate);
     }
 
     //-----------------------------------------------------------------------
     /**
      * Constructor that wraps (not copies).
-     * <p>
+     * <p>If there are any elements already in the bag being decorated, they
-     * If there are any elements already in the bag being decorated, they
+     * are validated.</p>
-     * are validated.
      * 
      * @param bag  the bag to decorate, must not be null
      * @param predicate  the predicate to use for validation, must not be null
@@ -89,14 +89,24 @@ public class PredicatedSortedBag<E>
     }
     
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public E first() {
         return decorated().first();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public E last() {
         return decorated().last();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public Comparator<? super E> comparator() {
         return decorated().comparator();
     }

src/main/java/org/apache/commons/collections/bag/SynchronizedBag.java

@@ -27,9 +27,9 @@ 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.
+ * Iterators must be separately synchronized around the loop.</p>
  * <p>
- * This class is Serializable from Commons Collections 3.1.
+ * This class is Serializable from Commons Collections 3.1.</p>
  *
  * @since Commons Collections 3.0
  * @version $Revision$
@@ -45,12 +45,13 @@ public class SynchronizedBag<E>
     /**
      * Factory method to create a synchronized bag.
      * 
+     * @param <E> the type of the elements in the bag
      * @param bag  the bag to decorate, must not be null
      * @return a new synchronized Bag
      * @throws IllegalArgumentException if bag is null
      */
-    public static <T> Bag<T> synchronizedBag(Bag<T> bag) {
+    public static <E> SynchronizedBag<E> synchronizedBag(Bag<E> bag) {
-        return new SynchronizedBag<T>(bag);
+        return new SynchronizedBag<E>(bag);
     }
     
     //-----------------------------------------------------------------------
@@ -85,18 +86,28 @@ public class SynchronizedBag<E>
     }
     
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public boolean add(E object, int count) {
         synchronized (lock) {
             return getBag().add(object, count);
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public boolean remove(Object object, int count) {
         synchronized (lock) {
             return getBag().remove(object, count);
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public Set<E> uniqueSet() {
         synchronized (lock) {
             Set<E> set = getBag().uniqueSet();
@@ -104,6 +115,9 @@ public class SynchronizedBag<E>
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public int getCount(Object object) {
         synchronized (lock) {
             return getBag().getCount(object);

src/main/java/org/apache/commons/collections/bag/SynchronizedSortedBag.java

@@ -26,9 +26,9 @@ 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.
+ * Iterators must be separately synchronized around the loop.</p>
  * <p>
- * This class is Serializable from Commons Collections 3.1.
+ * This class is Serializable from Commons Collections 3.1.</p>
  *
  * @since Commons Collections 3.0
  * @version $Revision$
@@ -44,11 +44,12 @@ public class SynchronizedSortedBag<E>
     /**
      * Factory method to create a synchronized sorted bag.
      * 
+     * @param <E> the type of the elements in the bag
      * @param bag  the bag to decorate, must not be null
      * @return a new synchronized SortedBag
      * @throws IllegalArgumentException if bag is null
      */
-    public static <E> SortedBag<E> synchronizedSortedBag(SortedBag<E> bag) {
+    public static <E> SynchronizedSortedBag<E> synchronizedSortedBag(SortedBag<E> bag) {
         return new SynchronizedSortedBag<E>(bag);
     }
     
@@ -84,18 +85,28 @@ public class SynchronizedSortedBag<E>
     }
     
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public synchronized E first() {
         synchronized (lock) {
             return getSortedBag().first();
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public synchronized E last() {
         synchronized (lock) {
             return getSortedBag().last();
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public synchronized Comparator<? super E> comparator() {
         synchronized (lock) {
             return getSortedBag().comparator();

src/main/java/org/apache/commons/collections/bag/TransformedBag.java

@@ -29,9 +29,9 @@ import org.apache.commons.collections.set.TransformedSet;
  * The add methods are affected by this class.
  * Thus objects must be removed or searched for using their transformed form.
  * For example, if the transformation converts Strings to Integers, you must
- * use the Integer form to remove objects.
+ * use the Integer form to remove objects.</p>
  * <p>
- * This class is Serializable from Commons Collections 3.1.
+ * This class is Serializable from Commons Collections 3.1.</p>
  *
  * @since Commons Collections 3.0
  * @version $Revision$
@@ -48,9 +48,9 @@ public class TransformedBag<E>
      * Factory method to create a transforming bag.
      * <p>
      * If there are any elements already in the bag being decorated, they
-     * are NOT transformed.
+     * are NOT transformed. Contrast this with {@link #transformedBag(Bag, Transformer)}.</p>
-     * Contrast this with {@link #transformedBag(Bag, Transformer)}.
      * 
+     * @param <E> the type of the elements in the bag
      * @param bag  the bag to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
      * @return a new transformed Bag
@@ -66,8 +66,9 @@ public class TransformedBag<E>
      * <p>
      * If there are any elements already in the bag being decorated, they
      * will be transformed by this method.
-     * Contrast this with {@link #transformingBag(Bag, Transformer)}.
+     * Contrast this with {@link #transformingBag(Bag, Transformer)}.</p>
      * 
+     * @param <E> the type of the elements in the bag
      * @param bag  the bag to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
      * @return a new transformed Bag
@@ -92,7 +93,7 @@ public class TransformedBag<E>
      * Constructor that wraps (not copies).
      * <p>
      * If there are any elements already in the bag being decorated, they
-     * are NOT transformed.
+     * are NOT transformed.</p>
      * 
      * @param bag  the bag to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
@@ -112,19 +113,33 @@ public class TransformedBag<E>
     }
 
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public int getCount(Object object) {
         return getBag().getCount(object);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public boolean remove(Object object, int nCopies) {
         return getBag().remove(object, nCopies);
     }
 
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public boolean add(E object, int nCopies) {
         return getBag().add(transform(object), nCopies);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public Set<E> uniqueSet() {
         Set<E> set = getBag().uniqueSet();
         return TransformedSet.<E>transformingSet(set, transformer);

src/main/java/org/apache/commons/collections/bag/TransformedSortedBag.java

@@ -27,9 +27,9 @@ import org.apache.commons.collections.Transformer;
  * The add methods are affected by this class.
  * Thus objects must be removed or searched for using their transformed form.
  * For example, if the transformation converts Strings to Integers, you must
- * use the Integer form to remove objects.
+ * use the Integer form to remove objects.</p>
  * <p>
- * This class is Serializable from Commons Collections 3.1.
+ * This class is Serializable from Commons Collections 3.1.</p>
  *
  * @since Commons Collections 3.0
  * @version $Revision$
@@ -46,15 +46,16 @@ public class TransformedSortedBag<E>
      * Factory method to create a transforming sorted bag.
      * <p>
      * If there are any elements already in the bag being decorated, they
-     * are NOT transformed.
+     * are NOT transformed. Contrast this with {@link #transformedSortedBag(SortedBag, Transformer)}.</p>
-     * Contrast this with {@link #transformedSortedBag(SortedBag, Transformer)}.
      * 
+     * @param <E> the type of the elements in the bag
      * @param bag  the bag to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
      * @return a new transformed SortedBag
      * @throws IllegalArgumentException if bag or transformer is null
      */
-    public static <E> SortedBag<E> transformingSortedBag(SortedBag<E> bag, Transformer<? super E, ? extends E> transformer) {
+    public static <E> TransformedSortedBag<E> transformingSortedBag(SortedBag<E> bag,
+                                                                    Transformer<? super E, ? extends E> transformer) {
         return new TransformedSortedBag<E>(bag, transformer);
     }
     
@@ -64,15 +65,17 @@ public class TransformedSortedBag<E>
      * <p>
      * If there are any elements already in the bag being decorated, they
      * will be transformed by this method.
-     * Contrast this with {@link #transformingSortedBag(SortedBag, Transformer)}.
+     * Contrast this with {@link #transformingSortedBag(SortedBag, Transformer)}.</p>
      * 
+     * @param <E> the type of the elements in the bag
      * @param bag  the bag to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
      * @return a new transformed SortedBag
      * @throws IllegalArgumentException if bag or transformer is null
      * @since Commons Collections 3.3
      */
-    public static <E> SortedBag<E> transformedSortedBag(SortedBag<E> bag, Transformer<? super E, ? extends E> transformer) {
+    public static <E> TransformedSortedBag<E> transformedSortedBag(SortedBag<E> bag,
+                                                                   Transformer<? super E, ? extends E> transformer) {
         TransformedSortedBag<E>  decorated = new TransformedSortedBag<E>(bag, transformer);
         if (transformer != null && bag != null && bag.size() > 0) {
             @SuppressWarnings("unchecked") // bag is type E
@@ -90,7 +93,7 @@ public class TransformedSortedBag<E>
      * Constructor that wraps (not copies).
      * <p>
      * If there are any elements already in the bag being decorated, they
-     * are NOT transformed.
+     * are NOT transformed.</p>
      * 
      * @param bag  the bag to decorate, must not be null
      * @param transformer  the transformer to use for conversion, must not be null
@@ -110,14 +113,24 @@ public class TransformedSortedBag<E>
     }
 
     //-----------------------------------------------------------------------
+    
+    /**
+     * {@inheritDoc}
+     */
     public E first() {
         return getSortedBag().first();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public E last() {
         return getSortedBag().last();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public Comparator<? super E> comparator() {
         return getSortedBag().comparator();
     }

src/main/java/org/apache/commons/collections/bag/UnmodifiableBag.java

@@ -32,9 +32,9 @@ import org.apache.commons.collections.set.UnmodifiableSet;
 /**
  * Decorates another <code>Bag</code> to ensure it can't be altered.
  * <p>
- * This class is Serializable from Commons Collections 3.1.
+ * This class is Serializable from Commons Collections 3.1.</p>
  * <p>
- * Attempts to modify it will result in an UnsupportedOperationException. 
+ * Attempts to modify it will result in an UnsupportedOperationException.</p> 
  *
  * @since Commons Collections 3.0
  * @version $Revision$
@@ -50,8 +50,9 @@ public final class UnmodifiableBag<E>
     /**
      * Factory method to create an unmodifiable bag.
      * <p>
-     * If the bag passed in is already unmodifiable, it is returned.
+     * If the bag passed in is already unmodifiable, it is returned.</p>
      * 
+     * @param <E> the type of the elements in the bag
      * @param bag  the bag to decorate, must not be null
      * @return an unmodifiable Bag
      * @throws IllegalArgumentException if bag is null

src/main/java/org/apache/commons/collections/bag/UnmodifiableSortedBag.java

@@ -32,9 +32,9 @@ import org.apache.commons.collections.set.UnmodifiableSet;
 /**
  * Decorates another <code>SortedBag</code> to ensure it can't be altered.
  * <p>
- * This class is Serializable from Commons Collections 3.1.
+ * This class is Serializable from Commons Collections 3.1.</p>
  * <p>
- * Attempts to modify it will result in an UnsupportedOperationException. 
+ * Attempts to modify it will result in an UnsupportedOperationException.</p> 
  *
  * @since Commons Collections 3.0
  * @version $Revision$
@@ -50,8 +50,9 @@ public final class UnmodifiableSortedBag<E>
     /**
      * Factory method to create an unmodifiable bag.
      * <p>
-     * If the bag passed in is already unmodifiable, it is returned.
+     * If the bag passed in is already unmodifiable, it is returned.</p>
      * 
+     * @param <E> the type of the elements in the bag
      * @param bag  the bag to decorate, must not be null
      * @return an unmodifiable SortedBag
      * @throws IllegalArgumentException if bag is null