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@271545 13f79535-47bb-0310-9956-ffa450edef68

src/main/org/apache/tools/ant/TaskContainer.java

@@ -1,7 +1,7 @@
 /*
  * The Apache Software License, Version 1.1
  *
- * Copyright (c) 2001 The Apache Software Foundation.  All rights
+ * Copyright (c) 2001-2002 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -55,20 +55,24 @@
 package org.apache.tools.ant;
 
 /**
- * Interface for objects which can contain tasks 
- *
- * <p>It is recommended that implementations call {@link Task#perform
- * perform} instead of {@link Task#execute execute} for the tasks they
- * contain, as this method ensures that {@link BuildEvent BuildEvents}
- * will be generated.</p>
+ * Interface for objects which can contain tasks.
+ * <p>
+ * It is recommended that implementations call perform rather than
+ * execute for the tasks they contain, as this method ensures that the
+ * appropriate BuildEvents will be generated.
  *
+ * @see Task#perform
+ * @see Task#execute
+ * @see BuildEvent
+ * 
  * @author <a href="mailto:conor@apache.org">Conor MacNeill</a>
  */
 public interface TaskContainer {
     /**
-     * Add a task to this task container
+     * Adds a task to this task container
      *
-     * @param task the task to be added to this container
+     * @param task The task to be added to this container.
+     *             Must not be <code>null</code>.
      */
     void addTask(Task task);
 }

src/main/org/apache/tools/ant/listener/MailLogger.java

@@ -95,7 +95,6 @@ import org.apache.tools.mail.MailMessage;
  *  file will override Ant properties.
  *
  *@author     Erik Hatcher <a href="mailto:ehatcher@apache.org">ehatcher@apache.org</a>
- *@created    December 12, 2001
  */
 public class MailLogger extends DefaultLogger {
 

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

@@ -140,6 +140,8 @@ public class KeySubst extends Task {
         this.sep = sep;
     }
     /**
+     * Sets the keys.
+     * 
         Format string is like this:
         <p>
         name=value*name2=value
@@ -184,7 +186,7 @@ public class KeySubst extends Task {
     /**
         Does replacement on text using the hashtable of keys.
         
-        @returns the string with the replacements in it.
+        @return the string with the replacements in it.
     */
     public static String replace ( String origString, Hashtable keys )
         throws BuildException

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

@@ -64,7 +64,6 @@ import java.io.*;
  * Load a file into a property
  *
  * @author Steve Loughran
- * @created 10 December 2001
  */
 public class LoadFile extends Task {
 

src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTask.java

@@ -357,7 +357,7 @@ public class JUnitTask 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/optional/junit/XMLResultAggregator.java

@@ -105,7 +105,7 @@ public class XMLResultAggregator extends Task implements XMLConstants {
 
     protected Vector transformers = new Vector();
 
-    /** the default directory: <tt>.</tt>. It is resolved from the project directory */
+    /** The default directory: <tt>&#046;</tt>. It is resolved from the project directory */
     public final static String DEFAULT_DIR = ".";
 
     /** the default file name: <tt>TESTS-TestSuites.xml</tt> */
@@ -307,8 +307,8 @@ public class XMLResultAggregator extends Task implements XMLConstants {
     /**
      * Create a new document builder. Will issue an <tt>ExceptionInitializerError</tt>
      * if something is going wrong. It is fatal anyway.
+     * To-do: factorize this somewhere else. It is duplicated code.
      * @return a new document builder to create a DOM
-     * @todo factorize this somewhere else. It is duplicated code.
      */
     private static DocumentBuilder getDocumentBuilder() {
         try {

src/main/org/apache/tools/ant/taskdefs/optional/junit/Xalan1Executor.java

@@ -63,7 +63,7 @@ import org.apache.xalan.xslt.XSLTResultTarget;
 /**
  * Xalan 1 executor. It will need a lot of things in the classpath:
  * xerces for the serialization, xalan and bsf for the extension.
- * @todo do everything via reflection to avoid compile problems ?
+ * To-do: do everything via reflection to avoid compile problems ?
  */
 public class Xalan1Executor extends XalanExecutor {
     void execute() throws Exception {

src/main/org/apache/tools/ant/types/CommandlineJava.java

@@ -64,9 +64,9 @@ import org.apache.tools.ant.taskdefs.condition.Os;
 
 /**
  * A representation of a Java command line that is nothing more
- * than a composite of 2 <tt>Commandline</tt>. 1 for the vm/options and
- * 1 for the classname/arguments. It provides specific methods for
- * a java command line.
+ * than a composite of 2 <tt>Commandline</tt>. One is used for the 
+ * vm/options and one for the classname/arguments. It provides 
+ * specific methods for a java command line.
  *
  * @author thomas.haas@softwired-inc.com
  * @author <a href="mailto:sbailliez@apache.org">Stephane Bailliez</a>

src/main/org/apache/tools/ant/types/FilterSet.java

@@ -75,7 +75,6 @@ import org.apache.tools.ant.Project;
  * A filter set may have begintoken and endtokens defined.
  *
  * @author     <A href="mailto:gholam@xtra.co.nz">  Michael McCallum  </A>
- * @created   14 March 2001
  */
 public class FilterSet extends DataType implements Cloneable {
     
@@ -83,7 +82,6 @@ public class FilterSet extends DataType implements Cloneable {
      * Individual filter component of filterset
      *
      * @author    Michael McCallum
-     * @created   14 March 2001
      */
     public static class Filter {
         /** Token which will be replaced in the filter operation */
@@ -150,7 +148,6 @@ public class FilterSet extends DataType implements Cloneable {
      * The filtersfile nested element.
      *
      * @author    Michael McCallum
-     * @created   Thursday, April 19, 2001
      */
     public class FiltersFile {
         

src/main/org/apache/tools/ant/types/RegularExpression.java

@@ -87,7 +87,7 @@ import org.apache.tools.ant.util.regexp.RegexpFactory;
  *   />
  * </pre>
  *
- * @see org.apache.oro.regex.Perl5Compiler
+ * @see org.apache.oro.text.regex.Perl5Compiler
  * @see org.apache.regexp.RE
  * @see java.util.regex.Pattern
  *

src/main/org/apache/tools/ant/types/Substitution.java

@@ -68,7 +68,7 @@ import org.apache.tools.ant.types.DataType;
  *   />
  * </pre>
  *
- * @see org.apache.oro.text.regex.Perl5Substitition
+ * @see org.apache.oro.text.regex.Perl5Substitution
  * @author Matthew Inger <a href="mailto:mattinger@mindless.com">mattinger@mindless.com</a>
  */
 public class Substitution extends DataType

src/main/org/apache/tools/ant/util/PackageNameMapper.java

@@ -65,7 +65,6 @@ import java.io.File;
  * </pre>
  *
  *@author     Erik Hatcher
- *@created    December 29, 2001
  */
 public class PackageNameMapper extends GlobPatternMapper {
     /**

src/main/org/apache/tools/ant/util/regexp/RegexpFactory.java

@@ -112,11 +112,12 @@ public class RegexpFactory extends RegexpMatcherFactory
     }
 
     /**
-     * Wrapper over {@seee RegexpMatcherFactory#createInstance
-     * createInstance} that ensures that we are dealing with a Regexp
-     * implementation.
+     * Wrapper over RegexpMatcherFactory.createInstance that ensures that 
+     * we are dealing with a Regexp implementation.
      *
      * @since 1.3
+     * 
+     * @see RegexpMatcherFactory#createInstance(String)
      */
     protected Regexp createRegexpInstance(String classname) 
         throws BuildException {