Some Javadoc corrections.

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

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

@@ -218,8 +218,8 @@ public class Main implements AntMain {
 
     /**
      * This operation is expected to call {@link System#exit(int)}, which 
-     * is what the base version does. however, the option to do something
-     * different is there. 
+     * is what the base version does.
+     * However, it is possible to do something else.
      * @param exitCode code to exit with
      */
     protected void exit(int exitCode) {

src/main/org/apache/tools/ant/launch/Locator.java

@@ -133,7 +133,7 @@ public final class Locator {
      * <p>Prior to Java 1.4,
      * swallows '%' that are not followed by two characters.</p>
      *
-     * @see <a href="http://www.w3.org/TR/xml11/#dt-sysid">dt-sysid</a>
+     * See <a href="http://www.w3.org/TR/xml11/#dt-sysid">dt-sysid</a>
      * which makes some mention of how
      * characters not supported by URI Reference syntax should be escaped.
      *

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

@@ -193,7 +193,7 @@ public abstract class AbstractJarSignerTask extends Task {
     /**
      * Adds a path of files to sign.
      *
-     * @param a path of files to sign.
+     * @return a path of files to sign.
      * @since Ant 1.7
      */
     public Path createPath() {

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

@@ -126,10 +126,8 @@ public class AntStructure extends Task {
     /**
      * Writes the actual structure information.
      *
-     * <p>{@link StructurePrinter#printHead printHead}, {@link
-     * StructurePrinter#printTargetDecl printTargetDecl} and {@link
-     * StructurePrinter#printTail printTail} are called exactly once,
-     * {@link StructurePrinter#printElement printElement} once for
+     * <p>{@link #printHead}, {@link #printTargetDecl} and {@link #printTail}
+     * are called exactly once, {@link #printElementDecl} once for
      * each declared task and type.</p>
      */
     public static interface StructurePrinter {
@@ -157,7 +155,7 @@ public class AntStructure extends Task {
          * @param out PrintWriter to write to.
          * @param p Project instance for the current task
          * @param name element name.
-         * @param name class of the defined element.
+         * @param element class of the defined element.
          */
         void printElementDecl(PrintWriter out, Project p, String name,
                               Class element);

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

@@ -153,7 +153,7 @@ public class Expand extends Task {
     /**
      * This method is to be overridden by extending unarchival tasks.
      *
-     * @param r         the source resource
+     * @param srcR      the source resource
      * @param dir       the destination directory
      */
     protected void expandResource(Resource srcR, File dir) {

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

@@ -87,14 +87,14 @@ public class RecorderEntry implements BuildLogger, SubBuildListener {
     }
 
     /**
-     * @see BuildListener#buildStarted(BuildEvent)
+     * @see org.apache.tools.ant.BuildListener#buildStarted(BuildEvent)
      */
     public void buildStarted(BuildEvent event) {
         log("> BUILD STARTED", Project.MSG_DEBUG);
     }
 
     /**
-     * @see BuildListener#buildFinished(BuildEvent)
+     * @see org.apache.tools.ant.BuildListener#buildFinished(BuildEvent)
      */
     public void buildFinished(BuildEvent event) {
         log("< BUILD FINISHED", Project.MSG_DEBUG);
@@ -139,7 +139,7 @@ public class RecorderEntry implements BuildLogger, SubBuildListener {
     }
 
     /**
-     * @see BuildListener#targetStarted(BuildEvent)
+     * @see org.apache.tools.ant.BuildListener#targetStarted(BuildEvent)
      */
     public void targetStarted(BuildEvent event) {
         log(">> TARGET STARTED -- " + event.getTarget(), Project.MSG_DEBUG);
@@ -149,7 +149,7 @@ public class RecorderEntry implements BuildLogger, SubBuildListener {
     }
 
     /**
-     * @see BuildListener#targetFinished(BuildEvent)
+     * @see org.apache.tools.ant.BuildListener#targetFinished(BuildEvent)
      */
     public void targetFinished(BuildEvent event) {
         log("<< TARGET FINISHED -- " + event.getTarget(), Project.MSG_DEBUG);
@@ -161,14 +161,14 @@ public class RecorderEntry implements BuildLogger, SubBuildListener {
     }
 
     /**
-     * @see BuildListener#taskStarted(BuildEvent)
+     * @see org.apache.tools.ant.BuildListener#taskStarted(BuildEvent)
      */
     public void taskStarted(BuildEvent event) {
         log(">>> TASK STARTED -- " + event.getTask(), Project.MSG_DEBUG);
     }
 
     /**
-     * @see BuildListener#taskFinished(BuildEvent)
+     * @see org.apache.tools.ant.BuildListener#taskFinished(BuildEvent)
      */
     public void taskFinished(BuildEvent event) {
         log("<<< TASK FINISHED -- " + event.getTask(), Project.MSG_DEBUG);
@@ -176,7 +176,7 @@ public class RecorderEntry implements BuildLogger, SubBuildListener {
     }
 
     /**
-     * @see BuildListener#messageLogged(BuildEvent)
+     * @see org.apache.tools.ant.BuildListener#messageLogged(BuildEvent)
      */
     public void messageLogged(BuildEvent event) {
         log("--- MESSAGE LOGGED", Project.MSG_DEBUG);

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

@@ -339,7 +339,7 @@ public class Tar extends MatchingTask {
 
     /**
      * tar a resource
-     * @param file the resource to tar
+     * @param r the resource to tar
      * @param tOut the output stream
      * @param vPath the path name of the file to tar
      * @param tarFileSet the fileset that the file came from, may be null.
@@ -502,7 +502,7 @@ public class Tar extends MatchingTask {
 
     /**
      * Is the archive up to date in relationship to a list of files.
-     * @param files the files to check
+     * @param r the files to check
      * @return true if the archive is up to date.
      * @since Ant 1.7
      */

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

@@ -106,7 +106,7 @@ public class Untar extends Expand {
     /**
      * This method is to be overridden by extending unarchival tasks.
      *
-     * @param r         the source resource
+     * @param srcR      the source resource
      * @param dir       the destination directory
      * @since Ant 1.7
      */
@@ -190,7 +190,7 @@ public class Untar extends Expand {
          *  This method wraps the input stream with the
          *     corresponding decompression method
          *
-         *  @param file provides location information for BuildException
+         *  @param name provides location information for BuildException
          *  @param istream input stream
          *  @return input stream with on-the-fly decompression
          *  @exception IOException thrown by GZIPInputStream constructor

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

@@ -1164,7 +1164,7 @@ public class Zip extends MatchingTask {
      * third arg if they already know that the archive is
      * out-of-date.</p>
      *
-     * @param filesets The filesets to grab resources from
+     * @param rcs The filesets to grab resources from
      * @param zipFile intended archive file (may or may not exist)
      * @param needsUpdate whether we already know that the archive is
      * out-of-date.  Subclasses overriding this method are supposed to

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

@@ -73,11 +73,6 @@ public class ParserSupports extends ProjectComponent implements Condition {
         this.value = value;
     }
 
-    /**
-     * Validate the args, then try to set the feature or property
-     * @return
-     * @throws BuildException
-     */
     public boolean eval() throws BuildException {
         if (feature != null && property != null) {
             throw new BuildException(ERROR_BOTH_ATTRIBUTES);

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

@@ -41,7 +41,7 @@ public class ResourcesMatch implements Condition {
     /**
      * Set whether to treat resources as if they were text files,
      * ignoring line endings.
-     * @param astext whether to ignore line endings.
+     * @param asText whether to ignore line endings.
      */
     public void setAsText(boolean asText) {
         this.asText = asText;

src/main/org/apache/tools/ant/taskdefs/optional/SchemaValidate.java

@@ -89,8 +89,8 @@ public class SchemaValidate extends XMLValidateTask {
     }
 
     /**
-     * turn on XSD support in Xerces
-     * @return
+     * Turn on XSD support in Xerces.
+     * @return true on success, false on failure
      */
     public boolean enableXercesSchemaValidation() {
         try {
@@ -116,10 +116,10 @@ public class SchemaValidate extends XMLValidateTask {
     }
 
     /**
-     * set schema attributes in a JAXP12 engine
+     * Set schema attributes in a JAXP 1.2 engine.
      * @see <A href="http://java.sun.com/xml/jaxp/change-requests-11.html">
      * JAXP 1.2 Approved CHANGES</A>
-     * @return
+     * @return true on success, false on failure
      */
     public boolean enableJAXP12SchemaValidation() {
         try {
@@ -230,7 +230,7 @@ public class SchemaValidate extends XMLValidateTask {
      * Create a reader if the use of the class did not specify another one.
      * The reason to not use {@link JAXPUtils#getXMLReader()} was to
      * create our own factory with our own options.
-     * @return
+     * @return a default XML parser
      */
     protected XMLReader createDefaultReader() {
         SAXParserFactory factory = SAXParserFactory.newInstance();
@@ -274,7 +274,7 @@ public class SchemaValidate extends XMLValidateTask {
 
     /**
      * get the URL of the no namespace schema
-     * @return
+     * @return the schema URL
      */
     protected String getNoNamespaceSchemaURL() {
         if (anonymousSchema == null) {
@@ -465,10 +465,6 @@ public class SchemaValidate extends XMLValidateTask {
             return true;
         }
 
-        /**
-         * hashcode function
-         * @return
-         */
         public int hashCode() {
             int result;
             result = (namespace != null ? namespace.hashCode() : 0);

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/CSharp.java

@@ -380,12 +380,6 @@ public class CSharp extends DotnetCompile {
         return "cs";
     }
 
-    /**
-     * from a resource, get the resource param string
-     * @param resource
-     * @return a string containing the resource param, or a null string
-     * to conditionally exclude a resource.
-     */
     protected void createResourceParameter(NetCommand command, DotnetResource resource) {
         resource.getParameters(getProject(), command, true);
     }

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/DotnetCompile.java

@@ -874,7 +874,7 @@ public abstract class DotnetCompile
         }
     }
 
-    /**
+    /* XXX Javadoc makes little sense, rewrite
      * from a resource, get the
      * @param resource
      * @return a string containing the resource param, or a null string

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/DotnetResource.java

@@ -25,8 +25,9 @@ import java.util.Iterator;
 import org.apache.tools.ant.*;
 
 /**
- * class used by DotnetCompile to name resources, could be upgraded to a
- * datatype in the distant future. a resource maps to /res:file,name
+ * Used by {@link DotnetCompile} to name resources.
+ * Could be upgraded to a datatype in the distant future.
+ * A resource maps to /res:file,name
  */
 public class DotnetResource {
 
@@ -153,8 +154,6 @@ public class DotnetResource {
 
     /**
      * build the C# style parameter (which has no public/private option)
-     * 
-     * @return the built C# style parameter
      */
     public void getParameters(Project p, NetCommand command, boolean csharpStyle) {
         checkParameters();

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/JSharp.java

@@ -113,12 +113,6 @@ public class JSharp extends DotnetCompile {
         }
     }
 
-    /**
-     * from a resource, get the resource param
-     * @param resource
-     * @return a string containing the resource param, or a null string
-     * to conditionally exclude a resource.
-     */
     protected void createResourceParameter(NetCommand command, DotnetResource resource) {
         resource.getParameters(getProject(), command, true);
     }

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/VisualBasicCompile.java

@@ -346,12 +346,6 @@ public class VisualBasicCompile extends DotnetCompile {
         return "vb";
     }
 
-    /**
-     * from a resource, get the resource param
-     * @param resource
-     * @return a string containing the resource param, or a null string
-     * to conditionally exclude a resource.
-     */
     protected void createResourceParameter(NetCommand command, DotnetResource resource) {
         resource.getParameters(getProject(), command, false);
     }

src/main/org/apache/tools/ant/taskdefs/optional/dotnet/WsdlToDotnet.java

@@ -391,8 +391,8 @@ public class WsdlToDotnet extends Task  {
         }
 
         /**
-         * validate our settings then return either the url or the full file path.
-         * @return
+         * Validate our settings.
+         * @return either the URL or the full file path
          */
         public String evaluate() {
             validate();
@@ -448,8 +448,8 @@ public class WsdlToDotnet extends Task  {
         }
 
         /**
-         * return the timestamp of a file, or -1 for a url (meaning we do not know its age)
-         * @return
+         * Gets the file timestamp.
+         * @return the timestamp of a file, or -1 for a URL (meaning we do not know its age)
          */
         public long getTimestamp() {
             if (file != null) {
@@ -513,8 +513,8 @@ public class WsdlToDotnet extends Task  {
         }
 
         /**
-         * create the default compiler for this platform
-         * @return
+         * Create the default compiler for this platform.
+         * @return the default compiler
          */
         public static Compiler createDefaultCompiler() {
             Compiler c = new Compiler();
@@ -526,7 +526,7 @@ public class WsdlToDotnet extends Task  {
 
         /**
          * return the command to run
-         * @return
+         * @return the command
          */
         public String getCommand() {
             return compilerExecutables[getIndex()];
@@ -534,7 +534,7 @@ public class WsdlToDotnet extends Task  {
 
         /**
          * return any extra arguments for the compiler
-         * @return
+         * @return extra compiler arguments
          */
         public String[] getExtraArgs() {
             return extraCompilerArgs[getIndex()];

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

@@ -214,12 +214,6 @@ public class TarFileSet extends ArchiveFileSet {
         }
     }
 
-    /**
-     * A ArchiveFileset accepts another ArchiveFileSet or a FileSet as reference
-     * FileSets are often used by the war task for the lib attribute
-     * @param p the project to use
-     * @return the abstract fileset instance
-     */
     protected void configureFileSet(ArchiveFileSet zfs) {
         super.configureFileSet(zfs);
         if (zfs instanceof TarFileSet) {

src/main/org/apache/tools/ant/types/optional/AbstractScriptComponent.java

@@ -33,8 +33,8 @@ public abstract class AbstractScriptComponent extends ProjectComponent {
 
     /**
      * Get our script runner
-     * @return
-     */ 
+     * @return the runner
+     */
     public ScriptRunner getRunner() {
         return runner;
     }

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

@@ -654,7 +654,7 @@ public class FileUtils {
      *   <li>DOS style paths that start with a drive letter will have
      *     \ as the separator.</li>
      * </ul>
-     * Unlike <code>File#getCanonicalPath()</code> this method
+     * Unlike {@link File#getCanonicalPath()} this method
      * specifically does not resolve symbolic links.
      *
      * @param path the path to be normalized.
@@ -1072,7 +1072,7 @@ public class FileUtils {
      *
      * <p>The coding of the output is the same as what File.toURI().toASCIIString() produces</p>
      *
-     * @see <a href="http://www.w3.org/TR/xml11/#dt-sysid">dt-sysid</a>
+     * See <a href="http://www.w3.org/TR/xml11/#dt-sysid">dt-sysid</a>
      * which makes some mention of how
      * characters not supported by URI Reference syntax should be escaped.
      *
@@ -1349,7 +1349,7 @@ public class FileUtils {
     }
 
     /**
-     * Calculates the relative path between to files.
+     * Calculates the relative path between two files.
      * <p>
      * Implementation note:<br/> This function my throw an IOException if an
      * I/O error occurs because its use of the canonical pathname may require
@@ -1360,9 +1360,9 @@ public class FileUtils {
      *            the <code>File</code> to calculate the path from
      * @param toFile
      *            the <code>File</code> to calculate the path to
-     * @return
-     * @throws Exception
-     * @see {@link File#getCanonicalPath()}
+     * @return the relative path between the files
+     * @throws Exception for undocumented reasons
+     * @see File#getCanonicalPath()
      *
      * @since Ant 1.7
      */
@@ -1482,4 +1482,4 @@ public class FileUtils {
         return buffer.toString();
     }
 
-}
+}