Add javadoc, minor formatting.

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

src/main/java/org/apache/commons/collections/functors/ChainedTransformer.java

@@ -40,7 +40,8 @@ public class ChainedTransformer<T> implements Transformer<T, T>, Serializable {
 
     /**
      * Factory method that performs validation and copies the parameter array.
-     * 
+     *
+     * @param <T>  the object type
      * @param transformers  the transformers to chain, copied, no nulls
      * @return the <code>chained</code> transformer
      * @throws IllegalArgumentException if the transformers array is null
@@ -58,7 +59,8 @@ public class ChainedTransformer<T> implements Transformer<T, T>, Serializable {
      * Create a new Transformer that calls each transformer in turn, passing the 
      * result into the next transformer. The ordering is that of the iterator()
      * method on the collection.
-     * 
+     *
+     * @param <T>  the object type
      * @param transformers  a collection of transformers to chain
      * @return the <code>chained</code> transformer
      * @throws IllegalArgumentException if the transformers collection is null

src/main/java/org/apache/commons/collections/functors/CloneTransformer.java

@@ -38,7 +38,8 @@ public class CloneTransformer<T> implements Transformer<T, T>, Serializable {
 
     /**
      * Factory returning the singleton instance.
-     * 
+     *
+     * @param <T>  the type of the objects to be cloned
      * @return the singleton instance
      * @since 3.1
      */

src/main/java/org/apache/commons/collections/functors/ClosureTransformer.java

@@ -38,7 +38,8 @@ public class ClosureTransformer<T> implements Transformer<T, T>, Serializable {
 
     /**
      * Factory method that performs validation.
-     * 
+     *
+     * @param <T>  the type of the object to transform
      * @param closure  the closure to call, not null
      * @return the <code>closure</code> transformer
      * @throws IllegalArgumentException if the closure is null

src/main/java/org/apache/commons/collections/functors/ComparatorPredicate.java

@@ -118,7 +118,8 @@ public class ComparatorPredicate<T> implements Predicate<T>, Serializable {
      * @return the predicate
      * @throws IllegalArgumentException if comparator is null of criterion is invalid
      */
-    public static <T> Predicate<T> comparatorPredicate(final T object, final Comparator<T> comparator, final Criterion criterion) {
+    public static <T> Predicate<T> comparatorPredicate(final T object, final Comparator<T> comparator,
+                                                       final Criterion criterion) {
         if (comparator == null) {
             throw new IllegalArgumentException("Comparator must not be null.");
         }
@@ -157,6 +158,8 @@ public class ComparatorPredicate<T> implements Predicate<T>, Serializable {
      * @see org.apache.commons.collections.Predicate#evaluate(java.lang.Object)
      * @see java.util.Comparator#compare(java.lang.Object first, java.lang.Object second)
      * 
+     * @param target  the target object to compare to
+     * @return {@code true} if the comparison succeeds according to the selected criterion
      * @throws IllegalStateException if the criterion is invalid (really not possible)
      */
     public boolean evaluate(final T target) {

src/main/java/org/apache/commons/collections/functors/ConstantFactory.java

@@ -44,6 +44,7 @@ public class ConstantFactory<T> implements Factory<T>, Serializable {
     /**
      * Factory method that performs validation.
      *
+     * @param <T>  the type of the constant
      * @param constantToReturn  the constant object to return each time in the factory
      * @return the <code>constant</code> factory.
      */

src/main/java/org/apache/commons/collections/functors/ConstantTransformer.java

@@ -43,8 +43,9 @@ public class ConstantTransformer<I, O> implements Transformer<I, O>, Serializabl
 
     /**
      * Get a typed null instance.
-     * @param <I>
-     * @param <O>
+     *
+     * @param <I>  the input type
+     * @param <O>  the output type
      * @return Transformer<I, O> that always returns null.
      */
     @SuppressWarnings("unchecked")
@@ -55,6 +56,8 @@ public class ConstantTransformer<I, O> implements Transformer<I, O>, Serializabl
     /**
      * Transformer method that performs validation.
      *
+     * @param <I>  the input type
+     * @param <O>  the output type
      * @param constantToReturn  the constant object to return each time in the factory
      * @return the <code>constant</code> factory.
      */

src/main/java/org/apache/commons/collections/functors/DefaultEquator.java

@@ -19,7 +19,7 @@ package org.apache.commons.collections.functors;
 /**
  * Default {@link Equator} implementation.
  * 
- * @param <T>
+ * @param <T>  the types of object this {@link Equator} can evaluate.
  * @since 4.0
  * @version $Id$
  */
@@ -56,7 +56,7 @@ public class DefaultEquator<T> implements Equator<T> {
     /**
      * Get a typed {@link DefaultEquator} instance.
      * 
-     * @param <T>
+     * @param <T>  the object type
      * @return {@link DefaultEquator#INSTANCE}
      */
     @SuppressWarnings("unchecked")

src/main/java/org/apache/commons/collections/functors/ExceptionFactory.java

@@ -38,6 +38,7 @@ public final class ExceptionFactory<T> implements Factory<T>, Serializable {
     /**
      * Factory returning the singleton instance.
      * 
+     * @param <T>  the type the factory creates
      * @return the singleton instance
      * @since 3.1
      */

src/main/java/org/apache/commons/collections/functors/ExceptionPredicate.java

@@ -38,6 +38,7 @@ public final class ExceptionPredicate<T> implements Predicate<T>, Serializable {
     /**
      * Factory returning the singleton instance.
      *
+     * @param <T>  the object type
      * @return the singleton instance
      * @since 3.1
      */

src/main/java/org/apache/commons/collections/functors/ExceptionTransformer.java

@@ -38,6 +38,8 @@ public final class ExceptionTransformer<I, O> implements Transformer<I, O>, Seri
     /**
      * Factory returning the singleton instance.
      *
+     * @param <I>  the input type
+     * @param <O>  the output type
      * @return the singleton instance
      * @since 3.1
      */

src/main/java/org/apache/commons/collections/functors/FactoryTransformer.java

@@ -38,6 +38,8 @@ public class FactoryTransformer<I, O> implements Transformer<I, O>, Serializable
     /**
      * Factory method that performs validation.
      * 
+     * @param <I>  the input type
+     * @param <O>  the output type
      * @param factory  the factory to call, not null
      * @return the <code>factory</code> transformer
      * @throws IllegalArgumentException if the factory is null

src/main/java/org/apache/commons/collections/functors/FunctorUtils.java

@@ -105,7 +105,8 @@ class FunctorUtils {
         for (final Predicate<T> predicate : predicates) {
             preds[i] = predicate;
             if (preds[i] == null) {
-                throw new IllegalArgumentException("The predicate collection must not contain a null predicate, index " + i + " was null");
+                throw new IllegalArgumentException(
+                        "The predicate collection must not contain a null predicate, index " + i + " was null");
             }
             i++;
         }
@@ -137,7 +138,8 @@ class FunctorUtils {
         }
         for (int i = 0; i < closures.length; i++) {
             if (closures[i] == null) {
-                throw new IllegalArgumentException("The closure array must not contain a null closure, index " + i + " was null");
+                throw new IllegalArgumentException(
+                        "The closure array must not contain a null closure, index " + i + " was null");
             }
         }
     }

src/main/java/org/apache/commons/collections/functors/IfClosure.java

@@ -102,7 +102,8 @@ public class IfClosure<E> implements Closure<E>, Serializable {
      * @param trueClosure  closure used if true, not null
      * @param falseClosure  closure used if false, not null
      */
-    public IfClosure(final Predicate<? super E> predicate, final Closure<? super E> trueClosure, final Closure<? super E> falseClosure) {
+    public IfClosure(final Predicate<? super E> predicate, final Closure<? super E> trueClosure,
+                     final Closure<? super E> falseClosure) {
         super();
         iPredicate = predicate;
         iTrueClosure = trueClosure;

src/main/java/org/apache/commons/collections/functors/InstantiateFactory.java

@@ -46,12 +46,14 @@ public class InstantiateFactory<T> implements Factory<T>, Serializable {
     /**
      * Factory method that performs validation.
      * 
+     * @param <T>  the type the factory creates
      * @param classToInstantiate  the class to instantiate, not null
      * @param paramTypes  the constructor parameter types
      * @param args  the constructor arguments
      * @return a new instantiate factory
      */
-    public static <T> Factory<T> instantiateFactory(final Class<T> classToInstantiate, Class<?>[] paramTypes, Object[] args) {
+    public static <T> Factory<T> instantiateFactory(final Class<T> classToInstantiate, Class<?>[] paramTypes,
+                                                    Object[] args) {
         if (classToInstantiate == null) {
             throw new IllegalArgumentException("Class to instantiate must not be null");
         }

src/main/java/org/apache/commons/collections/functors/InstantiateTransformer.java

@@ -44,7 +44,8 @@ public class InstantiateTransformer<T> implements Transformer<Class<? extends T>
 
     /**
      * Get a typed no-arg instance.
-     * @param <T>
+     *
+     * @param <T>  the type of the objects to be created
      * @return Transformer<Class<? extends T>, T>
      */
     public static <T> Transformer<Class<? extends T>, T> instantiateTransformer() {
@@ -54,6 +55,7 @@ public class InstantiateTransformer<T> implements Transformer<Class<? extends T>
     /**
      * Transformer method that performs validation.
      *
+     * @param <T>  the type of the objects to be created
      * @param paramTypes  the constructor parameter types
      * @param args  the constructor arguments
      * @return an instantiate transformer

src/main/java/org/apache/commons/collections/functors/InvokerTransformer.java

@@ -44,6 +44,8 @@ public class InvokerTransformer<I, O> implements Transformer<I, O>, Serializable
     /**
      * Gets an instance of this transformer calling a specific method with no arguments.
      * 
+     * @param <I>  the input type
+     * @param <O>  the output type
      * @param methodName  the method name to call
      * @return an invoker transformer
      * @since 3.1
@@ -57,13 +59,16 @@ public class InvokerTransformer<I, O> implements Transformer<I, O>, Serializable
 
     /**
      * Gets an instance of this transformer calling a specific method with specific values.
-     * 
+     *
+     * @param <I>  the input type
+     * @param <O>  the output type
      * @param methodName  the method name to call
      * @param paramTypes  the parameter types of the method
      * @param args  the arguments to pass to the method
      * @return an invoker transformer
      */
-    public static <I, O> Transformer<I, O> invokerTransformer(final String methodName, Class<?>[] paramTypes, Object[] args) {
+    public static <I, O> Transformer<I, O> invokerTransformer(final String methodName, Class<?>[] paramTypes,
+                                                              Object[] args) {
         if (methodName == null) {
             throw new IllegalArgumentException("The method to invoke must not be null");
         }

src/main/java/org/apache/commons/collections/functors/MapTransformer.java

@@ -41,6 +41,8 @@ public final class MapTransformer<I, O> implements Transformer<I, O>, Serializab
      * <p>
      * If the map is null, a transformer that always returns null is returned.
      *
+     * @param <I>  the input type
+     * @param <O>  the output type
      * @param map the map, not cloned
      * @return the transformer
      */

src/main/java/org/apache/commons/collections/functors/NOPTransformer.java

@@ -37,6 +37,7 @@ public class NOPTransformer<T> implements Transformer<T, T>, Serializable {
     /**
      * Factory returning the singleton instance.
      *
+     * @param <T>  the input/output type
      * @return the singleton instance
      * @since 3.1
      */

src/main/java/org/apache/commons/collections/functors/OrPredicate.java

@@ -45,7 +45,8 @@ public final class OrPredicate<T> implements Predicate<T>, PredicateDecorator<T>
      * @return the <code>and</code> predicate
      * @throws IllegalArgumentException if either predicate is null
      */
-    public static <T> Predicate<T> orPredicate(final Predicate<? super T> predicate1, final Predicate<? super T> predicate2) {
+    public static <T> Predicate<T> orPredicate(final Predicate<? super T> predicate1,
+                                               final Predicate<? super T> predicate2) {
         if (predicate1 == null || predicate2 == null) {
             throw new IllegalArgumentException("Predicate must not be null");
         }

src/main/java/org/apache/commons/collections/functors/PredicateTransformer.java

@@ -39,6 +39,7 @@ public class PredicateTransformer<T> implements Transformer<T, Boolean>, Seriali
     /**
      * Factory method that performs validation.
      * 
+     * @param <T>  the input type
      * @param predicate  the predicate to call, not null
      * @return the <code>predicate</code> transformer
      * @throws IllegalArgumentException if the predicate is null

src/main/java/org/apache/commons/collections/functors/PrototypeFactory.java

@@ -48,6 +48,7 @@ public class PrototypeFactory {
      * <li>serialization clone
      * <ul>
      *
+     * @param <T>  the type the factory creates
      * @param prototype  the object to clone each time in the factory
      * @return the <code>prototype</code> factory, or a {@link ConstantFactory#NULL_INSTANCE} if
      * the {@code prototype} is {@code null}

src/main/java/org/apache/commons/collections/functors/StringValueTransformer.java

@@ -38,6 +38,7 @@ public final class StringValueTransformer<T> implements Transformer<T, String>,
     /**
      * Factory returning the singleton instance.
      *
+     * @param <T>  the input type
      * @return the singleton instance
      * @since 3.1
      */

src/main/java/org/apache/commons/collections/functors/SwitchTransformer.java

@@ -44,6 +44,8 @@ public class SwitchTransformer<I, O> implements Transformer<I, O>, Serializable
     /**
      * Factory method that performs validation and copies the parameter arrays.
      * 
+     * @param <I>  the input type
+     * @param <O>  the output type
      * @param predicates  array of predicates, cloned, no nulls
      * @param transformers  matching array of transformers, cloned, no nulls
      * @param defaultTransformer  the transformer to use if no match, null means return null
@@ -61,7 +63,8 @@ public class SwitchTransformer<I, O> implements Transformer<I, O>, Serializable
             throw new IllegalArgumentException("The predicate and transformer arrays must be the same size");
         }
         if (predicates.length == 0) {
-            return (Transformer<I, O>) (defaultTransformer == null ? ConstantTransformer.<I, O>nullTransformer() : defaultTransformer);
+            return (Transformer<I, O>) (defaultTransformer == null ? ConstantTransformer.<I, O>nullTransformer() :
+                                                                     defaultTransformer);
         }
         return new SwitchTransformer<I, O>(FunctorUtils.copy(predicates),
                                            FunctorUtils.copy(transformers),
@@ -79,7 +82,9 @@ public class SwitchTransformer<I, O> implements Transformer<I, O>, Serializable
      * null key. The ordering is that of the iterator() method on the entryset 
      * collection of the map.
      * 
-     * @param predicatesAndTransformers  a map of predicates to transformers
+     * @param <I>  the input type
+     * @param <O>  the output type
+     * @param map  a map of predicates to transformers
      * @return the <code>switch</code> transformer
      * @throws IllegalArgumentException if the map is null
      * @throws IllegalArgumentException if any transformer in the map is null
@@ -87,23 +92,26 @@ public class SwitchTransformer<I, O> implements Transformer<I, O>, Serializable
      */
     @SuppressWarnings("unchecked")
     public static <I, O> Transformer<I, O> switchTransformer(
-            final Map<? extends Predicate<? super I>, ? extends Transformer<? super I, ? extends O>> predicatesAndTransformers) {
-        if (predicatesAndTransformers == null) {
+            final Map<? extends Predicate<? super I>, ? extends Transformer<? super I, ? extends O>> map) {
+
+        if (map == null) {
             throw new IllegalArgumentException("The predicate and transformer map must not be null");
         }
-        if (predicatesAndTransformers.size() == 0) {
+        if (map.size() == 0) {
             return ConstantTransformer.<I, O>nullTransformer();
         }
         // convert to array like this to guarantee iterator() ordering
-        final Transformer<? super I, ? extends O> defaultTransformer = predicatesAndTransformers.remove(null);
-        final int size = predicatesAndTransformers.size();
+        final Transformer<? super I, ? extends O> defaultTransformer = map.remove(null);
+        final int size = map.size();
         if (size == 0) {
-            return (Transformer<I, O>) (defaultTransformer == null ? ConstantTransformer.<I, O>nullTransformer() : defaultTransformer);
+            return (Transformer<I, O>) (defaultTransformer == null ? ConstantTransformer.<I, O>nullTransformer() :
+                                                                     defaultTransformer);
         }
         final Transformer<? super I, ? extends O>[] transformers = new Transformer[size];
         final Predicate<? super I>[] preds = new Predicate[size];
         int i = 0;
-        for (final Map.Entry<? extends Predicate<? super I>, ? extends Transformer<? super I, ? extends O>> entry : predicatesAndTransformers.entrySet()) {
+        for (final Map.Entry<? extends Predicate<? super I>,
+                             ? extends Transformer<? super I, ? extends O>> entry : map.entrySet()) {
             preds[i] = entry.getKey();
             transformers[i] = entry.getValue();
             i++;
@@ -126,7 +134,8 @@ public class SwitchTransformer<I, O> implements Transformer<I, O>, Serializable
         super();
         iPredicates = predicates;
         iTransformers = transformers;
-        iDefault = (Transformer<? super I, ? extends O>) (defaultTransformer == null ? ConstantTransformer.<I, O>nullTransformer() : defaultTransformer);
+        iDefault = (Transformer<? super I, ? extends O>) (defaultTransformer == null ?
+                ConstantTransformer.<I, O>nullTransformer() : defaultTransformer);
     }
 
     /**

src/main/java/org/apache/commons/collections/functors/TransformedPredicate.java

@@ -66,7 +66,8 @@ public final class TransformedPredicate<T> implements Predicate<T>, PredicateDec
      * @param transformer  the transformer to use
      * @param predicate  the predicate to decorate
      */
-    public TransformedPredicate(final Transformer<? super T, ? extends T> transformer, final Predicate<? super T> predicate) {
+    public TransformedPredicate(final Transformer<? super T, ? extends T> transformer,
+                                final Predicate<? super T> predicate) {
         iTransformer = transformer;
         iPredicate = predicate;
     }