First pass of JavaDoc work just to get rid of warnings.

When this is complete, whole source tree should JavaDoc (with 1.4)
with no warnings. (With JDK1.3.1 the 1.4-regexp stuff generates
warnings, but that's all.)


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

src/main/org/apache/tools/ant/taskdefs/Ant.java

@@ -72,7 +72,7 @@ import java.util.Hashtable;
 import java.util.Enumeration;
 
 /**
- * Call Ant in a sub-project
+ * Call Ant in a sub-project.
  *
  *  <pre>
  *  &lt;target name=&quot;foo&quot; depends=&quot;init&quot;&gt;

src/main/org/apache/tools/ant/taskdefs/Checksum.java

@@ -102,7 +102,8 @@ public class Checksum extends MatchingTask implements Condition {
      */
     private String property;
     /**
-     * Create new destination file?  Defaults to false.
+     * Whether or not to create a new file.
+     * Defaults to <code>false</code>.
      */
     private boolean forceOverwrite;
     /**
@@ -173,8 +174,9 @@ public class Checksum extends MatchingTask implements Condition {
     }
 
     /**
-     * Overwrite existing file irrespective of whether it is newer than
-     * the source file?  Defaults to false.
+     * Whether or not to overwrite existing file irrespective of 
+     * whether it is newer than
+     * the source file.  Defaults to false.
      */
     public void setForceOverwrite(boolean forceOverwrite) {
         this.forceOverwrite = forceOverwrite;

src/main/org/apache/tools/ant/taskdefs/ConditionTask.java

@@ -60,7 +60,7 @@ import org.apache.tools.ant.taskdefs.condition.ConditionBase;
 
 /**
  * <condition> task as a generalization of <available> and
- * <uptodate>
+ * <uptodate>.
  *
  * <p>This task supports boolean logic as well as pluggable conditions
  * to decide, whether a property should be set.</p>

src/main/org/apache/tools/ant/taskdefs/Echo.java

@@ -131,7 +131,7 @@ public class Echo extends Task {
     }
 
     /**
-     * Set the logging level to one of
+     * Set the logging level. Level should be one of
      * <ul>
      *  <li>error</li>
      *  <li>warning</li>

src/main/org/apache/tools/ant/taskdefs/Jar.java

@@ -210,11 +210,14 @@ public class Jar extends Zip {
 
     /**
      * Create the index list to speed up classloading.
-     * This is a JDK 1.3+ specific feature and is enabled by default.
-     * {@link http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#JAR%20Index}
+     * This is a JDK 1.3+ specific feature and is enabled by default. See
+     * <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#JAR+Index">the
+     * JAR index specification</a> for more details.
+     * 
      * @param zOut the zip stream representing the jar being built.
      * @throws IOException thrown if there is an error while creating the
      * index and adding it to the zip stream.
+     * 
      */
     private void createIndexList(ZipOutputStream zOut) throws IOException {
         ByteArrayOutputStream baos = new ByteArrayOutputStream();

src/main/org/apache/tools/ant/taskdefs/Java.java

@@ -287,7 +287,7 @@ public class Java extends Task {
     }
 
     /**
-     * Use a completely new environment
+     * Use a completely new environment.
      *
      * <p>Will be ignored if we are not forking a new VM.
      *

src/main/org/apache/tools/ant/taskdefs/Parallel.java

@@ -154,7 +154,7 @@ public class Parallel extends Task
         private int taskNumber;
 
         /**
-         * Construct a new TaskThread<p>
+         * Construct a new TaskThread.<p>
          *
          * @param task the Task to be executed in a seperate thread
          */

src/main/org/apache/tools/ant/taskdefs/Recorder.java

@@ -92,7 +92,7 @@ public class Recorder extends Task {
      *  unset state (null).
      */
     private Boolean start = null;
-    /** What level to log?  -1 means not initialized yet. */
+    /** The level to log at. A level of -1 means not initialized yet. */
     private int loglevel = -1;
     /** The list of recorder entries. */
     private static Hashtable recorderEntries = new Hashtable();

src/main/org/apache/tools/ant/taskdefs/Sleep.java

@@ -62,7 +62,6 @@ import org.apache.tools.ant.BuildException;
  * A task to sleep for a period of time
  *
  * @author steve_l@iseran.com steve loughran
- * @created 01 May 2001
  */
 
 public class Sleep extends Task {
@@ -186,7 +185,7 @@ public class Sleep extends Task {
 
 
     /**
-     * Executes this build task. throws org.apache.tools.ant.BuildException
+     * Executes this build task. Throws org.apache.tools.ant.BuildException
      * if there is an error during task execution.
      *
      * @exception BuildException Description of Exception

src/main/org/apache/tools/ant/taskdefs/compilers/Gcj.java

@@ -70,8 +70,6 @@ public class Gcj extends DefaultCompilerAdapter {
 
     /**
      * Performs a compile using the gcj compiler.
-     *  
-     * @author tora@debian.org
      */
     public boolean execute() throws BuildException {
         Commandline cmd;

src/main/org/apache/tools/ant/taskdefs/compilers/Jikes.java

@@ -80,8 +80,6 @@ public class Jikes extends DefaultCompilerAdapter {
      * what they should do.
      *
      * It has been successfully tested with jikes >1.10
-     *
-     * @author skanthak@muehlheim.de
      */
     public boolean execute() throws BuildException {
         attributes.log("Using jikes compiler", Project.MSG_VERBOSE);

src/main/org/apache/tools/ant/taskdefs/compilers/Sj.java

@@ -68,7 +68,6 @@ public class Sj extends DefaultCompilerAdapter {
 
     /**
      * Performs a compile using the sj compiler from Symantec.
-     * @author don@bea.com
      */
     public boolean execute() throws BuildException {
         attributes.log("Using symantec java compiler", Project.MSG_VERBOSE);

src/main/org/apache/tools/ant/taskdefs/condition/FilesMatch.java

@@ -59,12 +59,11 @@ import java.io.File;
 import java.io.IOException;
 
 /**
- * compare two files for bitwise equality based on size and content. timestamps
+ * Compares two files for bitwise equality based on size and content. Timestamps
  * are not looked at at all.
  *
  * @author Steve Loughran
  * @version $Revision$
- * @created 12 January 2002
  * @since Ant 1.5
  */
 

src/main/org/apache/tools/ant/taskdefs/email/EmailTask.java

@@ -76,7 +76,6 @@ import org.apache.tools.ant.types.FileSet;
  * @author ehatcher@apache.org Erik Hatcher
  * @author paulo.gaspar@krankikom.de Paulo Gaspar
  * @author roxspring@yahoo.com Rob Oxspring
- * @created 10 Dec 2001
  * @since 1.5
  */
 public class EmailTask

src/main/org/apache/tools/ant/taskdefs/optional/ide/VAJAntTool.java

@@ -68,7 +68,7 @@ import org.apache.tools.ant.BuildException;
  * Additionally this class provides methods to save build info for
  * a project in the repository and load it from the repository
  *
- * @author: Wolf Siberski
+ * @author Wolf Siberski
  */
 public class VAJAntTool {
     private final static String TOOL_DATA_KEY = "AntTool";

src/main/org/apache/tools/ant/taskdefs/optional/ide/VAJAntToolGUI.java

@@ -108,7 +108,7 @@ import org.apache.tools.ant.util.DateUtils;
  * but in fact I did a lot of <i>code-beautification</i> ;-).
  * <p>
  * @version 1.0 h
- * @author: Christoph Wilhelms, TUI Infotec GmbH
+ * @author Christoph Wilhelms, TUI Infotec GmbH
  */
 public class VAJAntToolGUI extends Frame {
     /**

src/main/org/apache/tools/ant/taskdefs/optional/ide/VAJBuildInfo.java

@@ -338,8 +338,8 @@ class VAJBuildInfo implements Runnable {
     }
 
     /**
-     * Returns true, if the Ant project is initialized
-     * (i.e. buildfile loaded)
+     * Returns true, if the Ant project is initialized.
+     * (i.e., if the buildfile loaded).
      */
     public boolean isProjectInitialized() {
         return projectInitialized;

src/main/org/apache/tools/ant/taskdefs/optional/ide/VAJImport.java

@@ -114,7 +114,7 @@ import java.lang.reflect.Field;
  * </tr>
  * </table>
  *
- * @author: Glenn McAllister, inspired by a similar task written by Peter Kelley
+ * @author Glenn McAllister, inspired by a similar task written by Peter Kelley
  */
 public class VAJImport extends VAJTask {
     protected Vector filesets = new Vector();

src/main/org/apache/tools/ant/taskdefs/optional/ide/VAJProjectDescription.java

@@ -58,7 +58,7 @@ import org.apache.tools.ant.BuildException;
 
 /**
  * Type class. Holds information about a project edition.
- * @author: Wolf Siberski
+ * @author Wolf Siberski
  */
 public class VAJProjectDescription {
     private String name;

src/main/org/apache/tools/ant/taskdefs/optional/metamata/MParse.java

@@ -73,7 +73,7 @@ import java.util.Random;
 
 /**
  * Simple Metamata MParse task based on the original written by
- * <a href="mailto:thomas.haas@softwired-inc.com">Thomas Haas</a>
+ * <a href="mailto:thomas.haas@softwired-inc.com">Thomas Haas</a>.
  * 
  * This version was written for Metamata 2.0 available at
  * <a href="http://www.metamata.com">http://www.metamata.com</a>

src/main/org/apache/tools/ant/taskdefs/optional/net/MimeMail.java

@@ -68,7 +68,6 @@ import org.apache.tools.ant.taskdefs.email.EmailTask;
  * @author steve_l@iseran.com steve loughran
  * @author ehatcher@apache.org Erik Hatcher
  * @author paulo.gaspar@krankikom.de Paulo Gaspar
- * @created 01 May 2001
  */
 public class MimeMail extends EmailTask
 {

src/main/org/apache/tools/ant/taskdefs/optional/perforce/P4Base.java

@@ -92,7 +92,7 @@ public abstract class P4Base extends org.apache.tools.ant.Task {
     protected String P4Client = "";
     /** Perforce User (eg fbloggs) */
     protected String P4User = "";
-    /** Perforce view for commands (eg //projects/foobar/main/source/... )*/
+    /** Perforce view for commands. (eg //projects/foobar/main/source/... )*/
     protected String P4View = "";
 
     //P4 g-opts and cmd opts (rtfm)

src/main/org/apache/tools/ant/taskdefs/optional/pvcs/Pvcs.java

@@ -80,7 +80,7 @@ import org.apache.tools.ant.taskdefs.ExecuteStreamHandler;
 import org.apache.tools.ant.types.Commandline;
 
 /**
- * A task that fetches source files from a PVCS archive
+ * A task that fetches source files from a PVCS archive.
  *
  * <b>19-04-2001</b> <p>The task now has a more robust
  * parser. It allows for platform independant file paths

src/main/org/apache/tools/ant/taskdefs/optional/scm/AntStarTeamCheckOut.java

@@ -394,7 +394,7 @@ public class AntStarTeamCheckOut extends org.apache.tools.ant.Task
             else
             {
                 f = StarTeamFinder.findFolder(v.getRootFolder(), getFolderName());
-		assertTrue(null != f,"ERROR: " + getProjectName() + delim + getViewName() + delim +
+        assertTrue(null != f,"ERROR: " + getProjectName() + delim + getViewName() + delim +
                                                  v.getRootFolder() + delim + getFolderName() + delim +
                                                 " does not exist.");
             }
@@ -445,7 +445,7 @@ public class AntStarTeamCheckOut extends org.apache.tools.ant.Task
     }
 
     /**
-     * returns a file object that defines the root of the local checkout tree
+     * Returns a file object that defines the root of the local checkout tree.
      * Depending on the value of targetFolderAbsolute, this will be either
      * the targetFolder exactly as set by the user or the path formed by appending
      * the default folder onto the specified target folder.
@@ -453,48 +453,48 @@ public class AntStarTeamCheckOut extends org.apache.tools.ant.Task
      * @param v      view from which the file is checked out, supplies the "default folder"
      * @param rootSourceFolder   root folder of the checkout operation in Star Team
      * @return an object referencing the local file
-     * @see getTargetFolderAbsolute()
+     * @see #getTargetFolderAbsolute()
      */
     private java.io.File calcTargetFolder(View v, Folder rootSourceFolder)
     {
-	java.io.File root = new java.io.File(getTargetFolder());
+    java.io.File root = new java.io.File(getTargetFolder());
         if (!getTargetFolderAbsolute())
-	{
-	    // Create a variable dir that contains the name of
-	    // the StarTeam folder that is the root folder in this view.
-	    // Get the default path to the current view.
+    {
+        // Create a variable dir that contains the name of
+        // the StarTeam folder that is the root folder in this view.
+        // Get the default path to the current view.
             String defaultPath = v.getDefaultPath();
 
-	    // convert whatever separator char is in starteam to that of the target system.
-	    defaultPath=defaultPath.replace('/', java.io.File.separatorChar);
-	    defaultPath=defaultPath.replace('\\', java.io.File.separatorChar);
+        // convert whatever separator char is in starteam to that of the target system.
+        defaultPath=defaultPath.replace('/', java.io.File.separatorChar);
+        defaultPath=defaultPath.replace('\\', java.io.File.separatorChar);
 
-	    java.io.File dir = new java.io.File(defaultPath);
-	    String dirName = dir.getName();
+        java.io.File dir = new java.io.File(defaultPath);
+        String dirName = dir.getName();
 
             // If it ends with separator then strip it off
-	    if (dirName.endsWith(delim))
-	    {
-		dirName = dirName.substring(0, dirName.length()-1);
-	    }
-
-	    // Replace the projectName in the file's absolute path to the viewName.
-	    // This makes the root target of a checkout operation equal to:
-	    // targetFolder + dirName
-	    StringTokenizer pathTokenizer = new StringTokenizer(rootSourceFolder.getFolderHierarchy(), delim);
-	    String currentToken = null;
-	    boolean foundRoot = false;
-	    while (pathTokenizer.hasMoreTokens())
-	    {
-		currentToken = pathTokenizer.nextToken();
-		if (currentToken.equals(getProjectName()) && !foundRoot)
-		{
-		    currentToken = dirName;
-		    foundRoot = true;    // only want to do this the first time
-		}
-		root = new java.io.File(root, currentToken);
-	    }
-	}
+        if (dirName.endsWith(delim))
+        {
+        dirName = dirName.substring(0, dirName.length()-1);
+        }
+
+        // Replace the projectName in the file's absolute path to the viewName.
+        // This makes the root target of a checkout operation equal to:
+        // targetFolder + dirName
+        StringTokenizer pathTokenizer = new StringTokenizer(rootSourceFolder.getFolderHierarchy(), delim);
+        String currentToken = null;
+        boolean foundRoot = false;
+        while (pathTokenizer.hasMoreTokens())
+        {
+        currentToken = pathTokenizer.nextToken();
+        if (currentToken.equals(getProjectName()) && !foundRoot)
+        {
+            currentToken = dirName;
+            foundRoot = true;    // only want to do this the first time
+        }
+        root = new java.io.File(root, currentToken);
+        }
+    }
 
         return root;
     }
@@ -631,7 +631,7 @@ public class AntStarTeamCheckOut extends org.apache.tools.ant.Task
         com.starbase.starteam.File remote = (com.starbase.starteam.File)item;
 
         // The local file name is simply the local target path (tgt) which has
-	// been passed recursively down from the top of the tree, with the item's name appended.
+    // been passed recursively down from the top of the tree, with the item's name appended.
         java.io.File local = new java.io.File(tgt,(String)item.get(p1.getName()));
 
         try

src/main/org/apache/tools/ant/taskdefs/optional/sitraka/CovMerge.java

@@ -89,7 +89,7 @@ public class CovMerge extends Task {
     private boolean verbose;
 
     /**
-     * set the coverage home. it must point to JProbe coverage
+     * set the coverage home. It must point to JProbe coverage
      * directories where are stored native librairies and jars
      */
     public void setHome(File value) {

src/main/org/apache/tools/ant/taskdefs/optional/sitraka/CovReport.java

@@ -165,7 +165,7 @@ public class CovReport extends Task {
 
 
     /**
-     * Set the coverage home. it must point to JProbe coverage
+     * Set the coverage home. It must point to JProbe coverage
      * directories where are stored native libraries and jars.
      */
     public void setHome(File value) {

src/main/org/apache/tools/ant/taskdefs/optional/sitraka/Coverage.java

@@ -134,7 +134,7 @@ public class Coverage extends Task {
         home = value;
     }
 
-    /** seed name for snapshot file. can be null, default to snap */
+    /** seed name for snapshot file. Can be null, default to snap */
     public void setSeedname(String value) {
         seedName = value;
     }
@@ -192,7 +192,7 @@ public class Coverage extends Task {
         }
     }
 
-    /** none, coverage, all. can be null, default to none */
+    /** none, coverage, all. Can be null, default to none */
     public void setFinalsnapshot(String value) {
         finalSnapshot = value;
     }

src/main/org/apache/tools/ant/taskdefs/optional/sitraka/XMLReport.java

@@ -259,7 +259,7 @@ public class XMLReport {
     }
 
     /**
-     * Convert to a CovReport-like signature ie, <classname>.<method>()
+     * Convert to a CovReport-like signature - <classname>.<method>().
      */
     protected String getMethodSignature(ClassFile clazz, MethodInfo method) {
         StringBuffer buf = new StringBuffer(clazz.getFullName());

src/main/org/apache/tools/ant/taskdefs/optional/sitraka/bytecode/ClassPathLoader.java

@@ -235,7 +235,7 @@ final class NullLoader implements ClassPathLoader.FileLoader {
 
 /**
  * jar loader specified in looking for classes in jar and zip
- * @todo read the jar manifest in case there is a Class-Path
+ * To-do: read the jar manifest in case there is a Class-Path
  * entry.
  */
 final class JarLoader implements ClassPathLoader.FileLoader {
@@ -270,7 +270,7 @@ final class JarLoader implements ClassPathLoader.FileLoader {
 
 /**
  * directory loader that will look all classes recursively
- * @todo should discard classes which package name does not
+ * To-do: should discard classes which package name does not
  * match the directory ?
  */
 final class DirectoryLoader implements ClassPathLoader.FileLoader {

src/main/org/apache/tools/ant/taskdefs/optional/sitraka/bytecode/MethodInfo.java

@@ -61,7 +61,7 @@ import org.apache.tools.ant.taskdefs.optional.sitraka.bytecode.attributes.Attrib
 
 /**
  * Method info structure.
- * @todo give a more appropriate name to methods.
+ * To-do: give a more appropriate name to methods.
  *
  * @author <a href="sbailliez@imediation.com">Stephane Bailliez</a>
  */

src/main/org/apache/tools/ant/taskdefs/optional/sos/SOS.java

@@ -64,7 +64,7 @@ import org.apache.tools.ant.types.Commandline;
 import org.apache.tools.ant.types.Path;
 
 /**
- * A base class for creating tasks for executing commands on SourceOffSite
+ * A base class for creating tasks for executing commands on SourceOffSite.
  * <p>
  * The class extends the 'exec' task as it operates by executing the soscmd(.exe) program
  * supplied with SOS. By default the task expects soscmd(.exe) to be in the path,
@@ -169,7 +169,7 @@ public abstract class SOS extends Task {
 
 
     /**
-     * Set the path to the item in SOS to operate on
+     * Set the path to the item in SOS to operate on.
      * <p>
      * To avoid the "$$" in th build file we add it here
      *
@@ -181,7 +181,7 @@ public abstract class SOS extends Task {
 
 
     /**
-     * Set the path to the location of the ss.ini
+     * Set the path to the location of the ss.ini.
      *
      * @param  vssServerPath  The new vssServerPath value
      */
@@ -440,7 +440,7 @@ public abstract class SOS extends Task {
 
 
     /**
-     * Builds and returns the working directory
+     * Builds and returns the working directory.
      * <p>
      * The localpath is created if it didn't exist
      *

src/main/org/apache/tools/ant/taskdefs/optional/sos/package.html

@@ -1,7 +1,7 @@
 <html>
 <body>
   <p>
-    Ant tasks for working with a SourceOffSite source control system
+    Ant tasks for working with a SourceOffSite source control system.
   </p>
   <p>
     The &lt;SOSGet&gt; Retreives file(s) from a SOS database<br>

src/main/org/apache/tools/ant/taskdefs/optional/starteam/StarTeamCheckin.java

@@ -144,7 +144,7 @@ public class StarTeamCheckin extends TreeBasedTask {
      * This attribute tells whether unlocked files on checkin (so that
      * other users may access them) checkout or to leave the checkout status
      * alone (default).
-     * @see setUnlocked()
+     * @see #setUnlocked(boolean)
      */
     private int lockStatus = Item.LockType.UNCHANGED;
 

src/main/org/apache/tools/ant/taskdefs/optional/starteam/StarTeamCheckout.java

@@ -135,8 +135,8 @@ public class StarTeamCheckout extends TreeBasedTask {
      * checkout locks all other users out from making changes.  An unlocked
      * checkout reverts all local files to their previous repository status
      * and removes the lock.
-     * @see setLocked()
-     * @see setUnlocked()
+     * @see #setLocked(boolean)
+     * @see #setUnlocked(boolean)
      */
     private int lockStatus = Item.LockType.UNCHANGED;