Add some comments to base task

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@270625 13f79535-47bb-0310-9956-ffa450edef68

proposal/sandbox/clearcase/src/main/org/apache/tools/ant/taskdefs/optional/clearcase/CCMatchingTask.java

@@ -63,33 +63,45 @@ import org.apache.tools.ant.BuildException;
 import org.apache.tools.ant.DirectoryScanner;
 
 /**
+ * Base task for all Clearcase tasks involving multiple-file processing.
  *
  * @author <a href="mailto:sbailliez@apache.org">Stephane Bailliez</a>
  */
 public abstract class CCMatchingTask extends MatchingTask {
-
+    
+    /** view path to use. Equivalent to base directory of processing */
     protected File viewpath;
 
+    /** cc helper tools */
     protected CCUtils utils = new CCUtils(this);
-
+    
+    /** the set of collected files to checkin */
     protected Hashtable files = null;
 
+    /** comments to use for the operation */
     protected String comment = null;
 
+    /** the comment file created from the comments. It avoids escaping issues */
     protected File commentFile;
 
+    /** cleartool options (and command as well) */
     protected String[] options;
 
-    public void setViewPath(File value){
-        this.viewpath = value;
-    }
-
-    public void setComment(String value){
-        comment = value;
-    }
-
+    /**
+     * @return a vector of options representing the cleartool arguments.
+     * The last arguments is normally allocated and replaced at the last
+     * moment before running the command.
+     * @see #execute(String[], CCFile)
+     */
     protected abstract Vector getOptions();
-
+    
+    /**
+     * @param file the clearcase file
+     * @return whether this file should be accepted or not by the
+     * command to restrict the file processing and errors. For
+     * example you might not want to checkin files that are
+     * already checked in and that are collected by the fileset
+     */
     protected boolean accept(CCFile file){
         return true;
     }
@@ -102,7 +114,8 @@ public abstract class CCMatchingTask extends MatchingTask {
             postExecute();
         }
     }
-
+    
+    /** check for attributes and builds the options array */
     protected void preExecute() throws BuildException {
         if (viewpath == null){
             throw new BuildException("Invalid viewpath");
@@ -114,13 +127,18 @@ public abstract class CCMatchingTask extends MatchingTask {
         options = new String[v.size()];
         v.copyInto(options);
     }
-
+    
+    /** clean up method calls after doExecute */
     protected void postExecute(){
         if (commentFile != null){
             commentFile.delete();
         }
     }
 
+    /**
+     * The core processing. It loops over all files and calls
+     * <tt>execute(String[], CCFile)</tt>
+     */
     protected void doExecute() throws BuildException {
         Enumeration elems = getFiles().elements();
         log("Processing " + files.size() + " elements...");
@@ -128,7 +146,16 @@ public abstract class CCMatchingTask extends MatchingTask {
             execute(options, (CCFile)elems.nextElement());
         }
     }
-
+    
+    /**
+     * Calls the cleartool command with the appropriate parameters. Note the
+     * the last array element is supposed to be used by the filepath.
+     * @param args the cleartool command to execute. The last element being allocated
+     * and representing the filepath.
+     * @param file the file element to process.
+     * @throws BuildException thrown if an error occurs when processing the
+     * cleartool command.
+     */
     protected void execute(String[] args, CCFile file) throws BuildException {
         args[args.length - 1] = file.getPath();
         CmdResult res = utils.cleartool(args);
@@ -137,6 +164,12 @@ public abstract class CCMatchingTask extends MatchingTask {
         }
     }
 
+    /**
+     * Restrict the set of files/directories to be processed.
+     * @return the set of files to be processed. The key is made up
+     * the filepath and the value is the <tt>CCFile</tt> instance.
+     * @see #accept(CCFile)
+     */
     protected Hashtable getFiles(){
         if (files != null){
             return files;
@@ -150,6 +183,14 @@ public abstract class CCMatchingTask extends MatchingTask {
         return files;
     }
 
+    /**
+     * Helper method to restrict a set of relative elements and add them
+     * to a map.
+     * @param map the map w/ a path/CCFile mapping to add elements to.
+     * @param basedir the base directory for all elements in the array.
+     * @param elems the set of elements to restrict.
+     * @see #accept(CCFile)
+     */
     protected void addElements(Hashtable map, File basedir, String[] elems){
         for (int i = 0; i < elems.length; i++){
             CCFile f = new CCFile(basedir, elems[i]);
@@ -158,4 +199,15 @@ public abstract class CCMatchingTask extends MatchingTask {
             }
         }
     }
+
+// Ant bean setters
+    
+    public void setViewPath(File value){
+        this.viewpath = value;
+    }
+
+    public void setComment(String value){
+        comment = value;
+    }
+
 }