From f99d6d6d41f0731013adfac0666c4ffa38924c16 Mon Sep 17 00:00:00 2001
From: Stephen Colebourne <scolebourne@apache.org>
Date: Sun, 16 May 2004 11:47:38 +0000
Subject: [PATCH] Javadoc

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@131725 13f79535-47bb-0310-9956-ffa450edef68
---
 .../collections/functors/ConstantFactory.java   |  7 +++++--
 .../collections/functors/ExceptionClosure.java  |  9 ++++++---
 .../collections/functors/ExceptionFactory.java  |  9 ++++++---
 .../collections/functors/ForClosure.java        |  8 ++++++--
 .../collections/functors/FunctorUtils.java      |  4 +++-
 .../commons/collections/functors/IfClosure.java |  9 +++++++--
 .../functors/InstantiateFactory.java            |  7 +++++--
 .../collections/functors/NOPClosure.java        |  8 +++++---
 .../collections/functors/NotNullPredicate.java  |  9 ++++++---
 .../collections/functors/PrototypeFactory.java  | 17 ++++++++++++-----
 .../collections/functors/SwitchClosure.java     | 11 ++++++++---
 .../functors/TransformerClosure.java            |  7 +++++--
 .../collections/functors/WhileClosure.java      |  9 +++++++--
 13 files changed, 81 insertions(+), 33 deletions(-)

diff --git a/src/java/org/apache/commons/collections/functors/ConstantFactory.java b/src/java/org/apache/commons/collections/functors/ConstantFactory.java
index c7d8a98b4..8396b8275 100644
--- a/src/java/org/apache/commons/collections/functors/ConstantFactory.java
+++ b/src/java/org/apache/commons/collections/functors/ConstantFactory.java
@@ -27,7 +27,7 @@ import org.apache.commons.collections.Factory;
  * use the prototype factory.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.4 $ $Date: 2004/03/13 17:17:03 $
+ * @version $Revision: 1.5 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -67,7 +67,9 @@ public class ConstantFactory implements Factory, Serializable {
     }
 
     /**
-     * Always return constant
+     * Always return constant.
+     * 
+     * @return the stored constant value
      */
     public Object create() {
         return iConstant;
@@ -75,6 +77,7 @@ public class ConstantFactory implements Factory, Serializable {
 
     /**
      * Gets the constant.
+     * 
      * @return the constant
      * @since Commons Collections 3.1
      */
diff --git a/src/java/org/apache/commons/collections/functors/ExceptionClosure.java b/src/java/org/apache/commons/collections/functors/ExceptionClosure.java
index 3f3dbd351..3098f619c 100644
--- a/src/java/org/apache/commons/collections/functors/ExceptionClosure.java
+++ b/src/java/org/apache/commons/collections/functors/ExceptionClosure.java
@@ -24,7 +24,7 @@ import org.apache.commons.collections.FunctorException;
  * Closure implementation that always throws an exception.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.6 $ $Date: 2004/03/31 23:13:04 $
+ * @version $Revision: 1.7 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -56,9 +56,12 @@ public final class ExceptionClosure implements Closure, Serializable {
 
     /**
      * Always throw an exception.
+     * 
+     * @param input  the input object
+     * @throws FunctorException always
      */
-    public void execute(Object object) {
+    public void execute(Object input) {
         throw new FunctorException("ExceptionClosure invoked");
     }
-    
+
 }
diff --git a/src/java/org/apache/commons/collections/functors/ExceptionFactory.java b/src/java/org/apache/commons/collections/functors/ExceptionFactory.java
index 24ab73e4f..5304c5235 100644
--- a/src/java/org/apache/commons/collections/functors/ExceptionFactory.java
+++ b/src/java/org/apache/commons/collections/functors/ExceptionFactory.java
@@ -24,7 +24,7 @@ import org.apache.commons.collections.FunctorException;
  * Factory implementation that always throws an exception.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.6 $ $Date: 2004/03/31 23:13:04 $
+ * @version $Revision: 1.7 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -55,10 +55,13 @@ public final class ExceptionFactory implements Factory, Serializable {
     }
 
     /**
-     * Always throw an exception.
+     * Always throws an exception.
+     * 
+     * @return never
+     * @throws FunctorException always
      */
     public Object create() {
         throw new FunctorException("ExceptionFactory invoked");
     }
-    
+
 }
diff --git a/src/java/org/apache/commons/collections/functors/ForClosure.java b/src/java/org/apache/commons/collections/functors/ForClosure.java
index 5f7857879..43e846809 100644
--- a/src/java/org/apache/commons/collections/functors/ForClosure.java
+++ b/src/java/org/apache/commons/collections/functors/ForClosure.java
@@ -23,7 +23,7 @@ import org.apache.commons.collections.Closure;
  * Closure implementation that calls another closure n times, like a for loop.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.4 $ $Date: 2004/03/13 17:17:03 $
+ * @version $Revision: 1.5 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -71,7 +71,9 @@ public class ForClosure implements Closure, Serializable {
     }
 
     /**
-     * Execute the closure count times.
+     * Executes the closure <code>count</code> times.
+     * 
+     * @param input  the input object
      */
     public void execute(Object input) {
         for (int i = 0; i < iCount; i++) {
@@ -81,6 +83,7 @@ public class ForClosure implements Closure, Serializable {
 
     /**
      * Gets the closure.
+     * 
      * @return the closure
      * @since Commons Collections 3.1
      */
@@ -90,6 +93,7 @@ public class ForClosure implements Closure, Serializable {
 
     /**
      * Gets the count.
+     * 
      * @return the count
      * @since Commons Collections 3.1
      */
diff --git a/src/java/org/apache/commons/collections/functors/FunctorUtils.java b/src/java/org/apache/commons/collections/functors/FunctorUtils.java
index 9526e6c56..22f84f9e4 100644
--- a/src/java/org/apache/commons/collections/functors/FunctorUtils.java
+++ b/src/java/org/apache/commons/collections/functors/FunctorUtils.java
@@ -26,7 +26,7 @@ import org.apache.commons.collections.Transformer;
  * Internal utilities for functors.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.6 $ $Date: 2004/02/18 00:59:20 $
+ * @version $Revision: 1.7 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -36,6 +36,7 @@ class FunctorUtils {
      * Restricted constructor.
      */
     private FunctorUtils() {
+        super();
     }
     
     /**
@@ -147,6 +148,7 @@ class FunctorUtils {
      * Copy method
      * 
      * @param transformers  the transformers to copy
+     * @return a clone of the transformers
      */
     static Transformer[] copy(Transformer[] transformers) {
         if (transformers == null) {
diff --git a/src/java/org/apache/commons/collections/functors/IfClosure.java b/src/java/org/apache/commons/collections/functors/IfClosure.java
index 1985ad811..19b403831 100644
--- a/src/java/org/apache/commons/collections/functors/IfClosure.java
+++ b/src/java/org/apache/commons/collections/functors/IfClosure.java
@@ -25,7 +25,7 @@ import org.apache.commons.collections.Predicate;
  * based on a predicate.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.5 $ $Date: 2004/03/13 17:17:03 $
+ * @version $Revision: 1.6 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -76,7 +76,9 @@ public class IfClosure implements Closure, Serializable {
     }
 
     /**
-     * Execute the correct closure.
+     * Executes the true or false closure accoring to the result of the predicate.
+     * 
+     * @param input  the input object
      */
     public void execute(Object input) {
         if (iPredicate.evaluate(input) == true) {
@@ -88,6 +90,7 @@ public class IfClosure implements Closure, Serializable {
 
     /**
      * Gets the predicate.
+     * 
      * @return the predicate
      * @since Commons Collections 3.1
      */
@@ -97,6 +100,7 @@ public class IfClosure implements Closure, Serializable {
 
     /**
      * Gets the closure called when true.
+     * 
      * @return the closure
      * @since Commons Collections 3.1
      */
@@ -106,6 +110,7 @@ public class IfClosure implements Closure, Serializable {
 
     /**
      * Gets the closure called when false.
+     * 
      * @return the closure
      * @since Commons Collections 3.1
      */
diff --git a/src/java/org/apache/commons/collections/functors/InstantiateFactory.java b/src/java/org/apache/commons/collections/functors/InstantiateFactory.java
index e59658488..6f4cac982 100644
--- a/src/java/org/apache/commons/collections/functors/InstantiateFactory.java
+++ b/src/java/org/apache/commons/collections/functors/InstantiateFactory.java
@@ -26,7 +26,7 @@ import org.apache.commons.collections.FunctorException;
  * Factory implementation that creates a new object instance by reflection.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.5 $ $Date: 2004/02/18 00:59:20 $
+ * @version $Revision: 1.6 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -50,6 +50,7 @@ public class InstantiateFactory implements Factory, Serializable {
      * @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 Factory getInstance(Class classToInstantiate, Class[] paramTypes, Object[] args) {
         if (classToInstantiate == null) {
@@ -113,7 +114,9 @@ public class InstantiateFactory implements Factory, Serializable {
     }
 
     /**
-     * Create the object using a constructor
+     * Creates an object using the stored constructor.
+     * 
+     * @return the new object
      */
     public Object create() {
         // needed for post-serialization
diff --git a/src/java/org/apache/commons/collections/functors/NOPClosure.java b/src/java/org/apache/commons/collections/functors/NOPClosure.java
index dc8b7caf9..98ca690be 100644
--- a/src/java/org/apache/commons/collections/functors/NOPClosure.java
+++ b/src/java/org/apache/commons/collections/functors/NOPClosure.java
@@ -23,7 +23,7 @@ import org.apache.commons.collections.Closure;
  * Closure implementation that does nothing.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.5 $ $Date: 2004/03/31 23:13:04 $
+ * @version $Revision: 1.6 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -53,10 +53,12 @@ public class NOPClosure implements Closure, Serializable {
     }
 
     /**
-     * Do nothing
+     * Do nothing.
+     * 
+     * @param input  the input object
      */
     public void execute(Object input) {
         // do nothing
     }
-    
+
 }
diff --git a/src/java/org/apache/commons/collections/functors/NotNullPredicate.java b/src/java/org/apache/commons/collections/functors/NotNullPredicate.java
index 411960bc0..2e7758f88 100644
--- a/src/java/org/apache/commons/collections/functors/NotNullPredicate.java
+++ b/src/java/org/apache/commons/collections/functors/NotNullPredicate.java
@@ -23,7 +23,7 @@ import org.apache.commons.collections.Predicate;
  * Predicate implementation that returns true if the input is not null.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.5 $ $Date: 2004/03/31 23:13:04 $
+ * @version $Revision: 1.6 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -53,10 +53,13 @@ public final class NotNullPredicate implements Predicate, Serializable {
     }
 
     /**
-     * Return true if the object equals null.
+     * Evaluates the predicate returning true if the object does not equal null.
+     * 
+     * @param object  the object to evaluate
+     * @return true if not null
      */
     public boolean evaluate(Object object) {
         return (object != null);
     }
-    
+
 }
diff --git a/src/java/org/apache/commons/collections/functors/PrototypeFactory.java b/src/java/org/apache/commons/collections/functors/PrototypeFactory.java
index 8d3a0bd44..b3390c49e 100644
--- a/src/java/org/apache/commons/collections/functors/PrototypeFactory.java
+++ b/src/java/org/apache/commons/collections/functors/PrototypeFactory.java
@@ -31,7 +31,7 @@ import org.apache.commons.collections.FunctorException;
  * Factory implementation that creates a new instance each time based on a prototype.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.6 $ $Date: 2004/02/18 00:59:20 $
+ * @version $Revision: 1.7 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -84,6 +84,7 @@ public class PrototypeFactory {
      * Use <code>getInstance</code> if you want that.
      */
     private PrototypeFactory() {
+        super();
     }
 
     // PrototypeCloneFactory
@@ -123,7 +124,9 @@ public class PrototypeFactory {
         }
 
         /**
-         * Return clone of prototype
+         * Creates an object by calling the clone method.
+         * 
+         * @return the new object
          */
         public Object create() {
             // needed for post-serialization
@@ -164,7 +167,9 @@ public class PrototypeFactory {
         }
 
         /**
-         * Return clone of prototype by serialization
+         * Creates an object using serialization.
+         * 
+         * @return the new object
          */
         public Object create() {
             ByteArrayOutputStream baos = new ByteArrayOutputStream(512);
@@ -186,13 +191,15 @@ public class PrototypeFactory {
                     if (bais != null) {
                         bais.close();
                     }
-                } catch (IOException ignored) {
+                } catch (IOException ex) {
+                    // ignore
                 }
                 try {
                     if (baos != null) {
                         baos.close();
                     }
-                } catch (IOException ignored) {
+                } catch (IOException ex) {
+                    // ignore
                 }
             }
         }
diff --git a/src/java/org/apache/commons/collections/functors/SwitchClosure.java b/src/java/org/apache/commons/collections/functors/SwitchClosure.java
index e697c8ab9..7cae97eb5 100644
--- a/src/java/org/apache/commons/collections/functors/SwitchClosure.java
+++ b/src/java/org/apache/commons/collections/functors/SwitchClosure.java
@@ -27,7 +27,7 @@ import org.apache.commons.collections.Predicate;
  * like a switch statement.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.4 $ $Date: 2004/03/13 17:17:03 $
+ * @version $Revision: 1.5 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -127,7 +127,9 @@ public class SwitchClosure implements Closure, Serializable {
     }
 
     /**
-     * Execute the closure whose predicate returns true
+     * Executes the closure whose matching predicate returns true
+     * 
+     * @param input  the input object
      */
     public void execute(Object input) {
         for (int i = 0; i < iPredicates.length; i++) {
@@ -141,6 +143,7 @@ public class SwitchClosure implements Closure, Serializable {
 
     /**
      * Gets the predicates, do not modify the array.
+     * 
      * @return the predicates
      * @since Commons Collections 3.1
      */
@@ -150,6 +153,7 @@ public class SwitchClosure implements Closure, Serializable {
 
     /**
      * Gets the closures, do not modify the array.
+     * 
      * @return the closures
      * @since Commons Collections 3.1
      */
@@ -159,11 +163,12 @@ public class SwitchClosure implements Closure, Serializable {
 
     /**
      * Gets the default closure.
+     * 
      * @return the default closure
      * @since Commons Collections 3.1
      */
     public Closure getDefaultClosure() {
         return iDefault;
     }
-
+    
 }
diff --git a/src/java/org/apache/commons/collections/functors/TransformerClosure.java b/src/java/org/apache/commons/collections/functors/TransformerClosure.java
index 3a8df1d1a..807384623 100644
--- a/src/java/org/apache/commons/collections/functors/TransformerClosure.java
+++ b/src/java/org/apache/commons/collections/functors/TransformerClosure.java
@@ -25,7 +25,7 @@ import org.apache.commons.collections.Transformer;
  * and ignore the result.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.4 $ $Date: 2004/03/13 17:17:03 $
+ * @version $Revision: 1.5 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -64,7 +64,9 @@ public class TransformerClosure implements Closure, Serializable {
     }
 
     /**
-     * Call the transformer.
+     * Executes the closure by calling the decorated transformer.
+     * 
+     * @param input  the input object
      */
     public void execute(Object input) {
         iTransformer.transform(input);
@@ -72,6 +74,7 @@ public class TransformerClosure implements Closure, Serializable {
 
     /**
      * Gets the transformer.
+     * 
      * @return the transformer
      * @since Commons Collections 3.1
      */
diff --git a/src/java/org/apache/commons/collections/functors/WhileClosure.java b/src/java/org/apache/commons/collections/functors/WhileClosure.java
index 57c1624b2..f39d6081f 100644
--- a/src/java/org/apache/commons/collections/functors/WhileClosure.java
+++ b/src/java/org/apache/commons/collections/functors/WhileClosure.java
@@ -25,7 +25,7 @@ import org.apache.commons.collections.Predicate;
  * like a do-while or while loop.
  * 
  * @since Commons Collections 3.0
- * @version $Revision: 1.4 $ $Date: 2004/03/13 17:17:03 $
+ * @version $Revision: 1.5 $ $Date: 2004/05/16 11:47:38 $
  *
  * @author Stephen Colebourne
  */
@@ -76,7 +76,9 @@ public class WhileClosure implements Closure, Serializable {
     }
 
     /**
-     * Execute the closure until the predicate is false.
+     * Executes the closure until the predicate is false.
+     * 
+     * @param input  the input object
      */
     public void execute(Object input) {
         if (iDoLoop) {
@@ -89,6 +91,7 @@ public class WhileClosure implements Closure, Serializable {
 
     /**
      * Gets the predicate in use.
+     * 
      * @return the predicate
      * @since Commons Collections 3.1
      */
@@ -98,6 +101,7 @@ public class WhileClosure implements Closure, Serializable {
 
     /**
      * Gets the closure.
+     * 
      * @return the closure
      * @since Commons Collections 3.1
      */
@@ -107,6 +111,7 @@ public class WhileClosure implements Closure, Serializable {
 
     /**
      * Is the loop a do-while loop.
+     * 
      * @return true is do-while, false if while
      * @since Commons Collections 3.1
      */