style

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

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

@@ -90,6 +90,7 @@ public abstract class AbstractCvsTask extends Task {
      * setCompression( true ).
      */
     public static final int DEFAULT_COMPRESSION_LEVEL = 3;
+    private static final int MAXIMUM_COMRESSION_LEVEL = 9;
 
     private Commandline cmd = new Commandline();
 
@@ -114,7 +115,7 @@ public abstract class AbstractCvsTask extends Task {
     /**
      * the default command.
      */
-    private static final String default_command = "checkout";
+    private static final String DEFAULT_COMMAND = "checkout";
     /**
      * the CVS command to execute.
      */
@@ -182,10 +183,18 @@ public abstract class AbstractCvsTask extends Task {
         super();
     }
 
+    /**
+     * sets the handler
+     * @param handler a handler able of processing the output and error streams from the cvs exe
+     */
     public void setExecuteStreamHandler(ExecuteStreamHandler handler) {
         this.executeStreamHandler = handler;
     }
 
+    /**
+     * find the handler and instantiate it if it does not exist yet
+     * @return handler for output and error streams
+     */
     protected ExecuteStreamHandler getExecuteStreamHandler() {
 
         if (this.executeStreamHandler == null) {
@@ -196,12 +205,23 @@ public abstract class AbstractCvsTask extends Task {
         return this.executeStreamHandler;
     }
 
-
+    /**
+     * sets a stream to which the output from the cvs executable should be sent
+     * @param outputStream stream to which the stdout from cvs should go
+     */
     protected void setOutputStream(OutputStream outputStream) {
 
         this.outputStream = outputStream;
     }
 
+    /**
+     * access the stream to which the stdout from cvs should go
+     * if this stream has already been set, it will be returned
+     * if the stream has not yet been set, if the attribute output
+     * has been set, the output stream will go to the output file
+     * otherwise the output will go to ant's logging system
+     * @return output stream to which cvs'stdout should go to
+     */
     protected OutputStream getOutputStream() {
 
         if (this.outputStream == null) {
@@ -224,11 +244,23 @@ public abstract class AbstractCvsTask extends Task {
         return this.outputStream;
     }
 
+    /**
+     * sets a stream to which the stderr from the cvs exe should go
+     * @param errorStream an output stream willing to process stderr
+     */
     protected void setErrorStream(OutputStream errorStream) {
 
         this.errorStream = errorStream;
     }
 
+    /**
+     * access the stream to which the stderr from cvs should go
+     * if this stream has already been set, it will be returned
+     * if the stream has not yet been set, if the attribute error
+     * has been set, the output stream will go to the file denoted by the error attribute
+     * otherwise the stderr output will go to ant's logging system
+     * @return output stream to which cvs'stderr should go to
+     */
     protected OutputStream getErrorStream() {
 
         if (this.errorStream == null) {
@@ -253,7 +285,8 @@ public abstract class AbstractCvsTask extends Task {
 
     /**
      * Sets up the environment for toExecute and then runs it.
-     * @throws BuildException
+     * @param toExecute the command line to execute
+     * @throws BuildException if failonError is set to true and the cvs command fails
      */
     protected void runCommand(Commandline toExecute) throws BuildException {
         // XXX: we should use JCVS (www.ice.com/JCVS) instead of
@@ -386,13 +419,17 @@ public abstract class AbstractCvsTask extends Task {
         }
     }
 
+    /**
+     * do the work
+     * @throws BuildException if failonerror is set to true and the cvs command fails.
+     */
     public void execute() throws BuildException {
 
         String savedCommand = getCommand();
 
         if (this.getCommand() == null && vecCommandlines.size() == 0) {
             // re-implement legacy behaviour:
-            this.setCommand(AbstractCvsTask.default_command);
+            this.setCommand(AbstractCvsTask.DEFAULT_COMMAND);
         }
 
         String c = this.getCommand();
@@ -442,7 +479,7 @@ public abstract class AbstractCvsTask extends Task {
     /**
      * The CVSROOT variable.
      *
-     * @param root
+     * @param root the CVSROOT variable
      */
     public void setCvsRoot(String root) {
 
@@ -456,6 +493,10 @@ public abstract class AbstractCvsTask extends Task {
         this.cvsRoot = root;
     }
 
+    /**
+     * access the the CVSROOT variable
+     * @return CVSROOT
+     */
     public String getCvsRoot() {
 
         return this.cvsRoot;
@@ -464,7 +505,7 @@ public abstract class AbstractCvsTask extends Task {
     /**
      * The CVS_RSH variable.
      *
-     * @param rsh
+     * @param rsh the CVS_RSH variable
      */
     public void setCvsRsh(String rsh) {
         // Check if not real cvsrsh => set it to null
@@ -477,6 +518,10 @@ public abstract class AbstractCvsTask extends Task {
         this.cvsRsh = rsh;
     }
 
+    /**
+     * access the CVS_RSH variable
+     * @return the CVS_RSH variable
+     */
     public String getCvsRsh() {
 
         return this.cvsRsh;
@@ -485,12 +530,16 @@ public abstract class AbstractCvsTask extends Task {
     /**
      * Port used by CVS to communicate with the server.
      *
-     * @param port
+     * @param port port of CVS
      */
     public void setPort(int port) {
         this.port = port;
     }
 
+    /**
+     * access the port of CVS
+     * @return the port of CVS
+     */
     public int getPort() {
 
         return this.port;
@@ -499,12 +548,16 @@ public abstract class AbstractCvsTask extends Task {
     /**
      * Password file to read passwords from.
      *
-     * @param passFile
+     * @param passFile password file to read passwords from
      */
     public void setPassfile(File passFile) {
         this.passFile = passFile;
     }
 
+    /**
+     * find the password file
+     * @return password file
+     */
     public File getPassFile() {
 
         return this.passFile;
@@ -513,12 +566,17 @@ public abstract class AbstractCvsTask extends Task {
     /**
      * The directory where the checked out files should be placed.
      *
-     * @param dest
+     * @param dest directory where the checked out files should be placed
      */
     public void setDest(File dest) {
         this.dest = dest;
     }
 
+    /**
+     * get the file where the checked out files should be placed
+     *
+     * @return directory where the checked out files should be placed
+     */
     public File getDest() {
 
         return this.dest;
@@ -527,12 +585,17 @@ public abstract class AbstractCvsTask extends Task {
     /**
      * The package/module to operate upon.
      *
-     * @param p
+     * @param p package or module to operate upon
      */
     public void setPackage(String p) {
         this.cvsPackage = p;
     }
 
+    /**
+     * access the package or module to operate upon
+     *
+     * @return package/module
+     */
     public String getPackage() {
 
         return this.cvsPackage;
@@ -540,7 +603,7 @@ public abstract class AbstractCvsTask extends Task {
 
     /**
      * The tag of the package/module to operate upon.
-     * @param p
+     * @param p tag
      */
     public void setTag(String p) {
         // Check if not real tag => set it to null
@@ -553,11 +616,22 @@ public abstract class AbstractCvsTask extends Task {
     /**
      * This needs to be public to allow configuration
      *      of commands externally.
+     * @param arg command argument
      */
     public void addCommandArgument(String arg) {
         this.addCommandArgument(cmd, arg);
     }
 
+    /**
+     * add a command line argument to an external command
+     *
+     * I do not understand what this method does in this class ???
+     * particulary not why it is public ????
+     * AntoineLL July 23d 2003
+     *
+     * @param c  command line to which one argument should be added
+     * @param arg argument to add
+     */
     public void addCommandArgument(Commandline c, String arg) {
         c.createArgument().setValue(arg);
     }
@@ -565,7 +639,8 @@ public abstract class AbstractCvsTask extends Task {
 
     /**
      * Use the most recent revision no later than the given date.
-     * @param p
+     * @param p a date as string in a format that the CVS executable can understand
+     * see man cvs
      */
     public void setDate(String p) {
         if (p != null && p.trim().length() > 0) {
@@ -576,18 +651,30 @@ public abstract class AbstractCvsTask extends Task {
 
     /**
      * The CVS command to execute.
-     * @param c
+     *
+     * This should be deprecated, it is better to use the Commandline class ?
+     * AntoineLL July 23d 2003
+     *
+     * @param c a command as string
      */
     public void setCommand(String c) {
         this.command = c;
     }
+    /**
+     * accessor to a command line as string
+     *
+     * This should be deprecated
+     * AntoineLL July 23d 2003
+     *
+     * @return command line as string
+     */
     public String getCommand() {
         return this.command;
     }
 
     /**
      * If true, suppress informational messages.
-     * @param q
+     * @param q  if true, suppress informational messages
      */
     public void setQuiet(boolean q) {
         quiet = q;
@@ -596,7 +683,7 @@ public abstract class AbstractCvsTask extends Task {
     /**
      * If true, report only and don't change any files.
      *
-     * @param ne
+     * @param ne if true, report only and do not change any files.
      */
     public void setNoexec(boolean ne) {
         noexec = ne;
@@ -604,7 +691,7 @@ public abstract class AbstractCvsTask extends Task {
 
     /**
      * The file to direct standard output from the command.
-     * @param output
+     * @param output a file to which stdout should go
      */
     public void setOutput(File output) {
         this.output = output;
@@ -613,7 +700,7 @@ public abstract class AbstractCvsTask extends Task {
     /**
      * The file to direct standard error from the command.
      *
-     * @param error
+     * @param error a file to which stderr should go
      */
     public void setError(File error) {
         this.error = error;
@@ -621,7 +708,7 @@ public abstract class AbstractCvsTask extends Task {
 
     /**
      * Whether to append output/error when redirecting to a file.
-     * @param value
+     * @param value true indicated you want to append
      */
     public void setAppend(boolean value) {
         this.append = value;
@@ -631,7 +718,8 @@ public abstract class AbstractCvsTask extends Task {
      * Stop the build process if the command exits with
      * a return code other than 0.
      * Defaults to false.
-     * @param failOnError
+     * @param failOnError stop the build process if the command exits with
+     * a return code other than 0
      */
     public void setFailOnError(boolean failOnError) {
         this.failOnError = failOnError;
@@ -639,6 +727,22 @@ public abstract class AbstractCvsTask extends Task {
 
     /**
      * Configure a commandline element for things like cvsRoot, quiet, etc.
+     * @param c the command line which will be configured
+     * if the commandline is initially null, the function is a noop
+     * otherwise the function append to the commandline arguments concerning
+     * <ul>
+     * <li>
+     * cvs package
+     * </li>
+     * <li>
+     * compression
+     * </li>
+     * <li>
+     * quiet
+     * </li>
+     * <li>cvsroot</li>
+     * <li>noexec</li>
+     * </ul>
      */
     protected void configureCommandline(Commandline c) {
         if (c == null) {
@@ -648,7 +752,7 @@ public abstract class AbstractCvsTask extends Task {
         if (cvsPackage != null) {
             c.createArgument().setLine(cvsPackage);
         }
-        if (this.compression > 0 && this.compression < 10) {
+        if (this.compression > 0 && this.compression <= MAXIMUM_COMRESSION_LEVEL) {
             c.createArgument(true).setValue("-z" + this.compression);
         }
         if (quiet) {
@@ -662,21 +766,27 @@ public abstract class AbstractCvsTask extends Task {
         }
     }
 
+    /**
+     * remove a particular command from a vector of command lines
+     * @param c command line which should be removed
+     */
     protected void removeCommandline(Commandline c) {
         vecCommandlines.removeElement(c);
     }
 
     /**
      * Adds direct command-line to execute.
-     * @param c
+     * @param c command line to execute
      */
     public void addConfiguredCommandline(Commandline c) {
         this.addConfiguredCommandline(c, false);
     }
 
     /**
-    * Configures and adds the given Commandline.
-    * @param insertAtStart If true, c is
+     * Configures and adds the given Commandline.
+     * @param c commandline to insert
+     * @param insertAtStart If true, c is
+     * inserted at the beginning of the vector of command lines
     */
     public void addConfiguredCommandline(Commandline c,
                                          boolean insertAtStart) {
@@ -694,6 +804,7 @@ public abstract class AbstractCvsTask extends Task {
     /**
     * If set to a value 1-9 it adds -zN to the cvs command line, else
     * it disables compression.
+     * @param level compression level 1 to 9
     */
     public void setCompressionLevel(int level) {
         this.compression = level;

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

@@ -136,6 +136,7 @@ public class Ant extends Task {
     /**
      * If true, pass all properties to the new Ant project.
      * Defaults to true.
+     * @param value if true pass all properties to the new Ant project.
      */
     public void setInheritAll(boolean value) {
         inheritAll = value;
@@ -144,6 +145,7 @@ public class Ant extends Task {
     /**
      * If true, pass all references to the new Ant project.
      * Defaults to false.
+     * @param value if true, pass all references to the new Ant project
      */
     public void setInheritRefs(boolean value) {
         inheritRefs = value;
@@ -261,6 +263,7 @@ public class Ant extends Task {
     /**
      * Pass output sent to System.out to the new project.
      *
+     * @param output a line of output
      * @since Ant 1.5
      */
     public void handleOutput(String output) {
@@ -272,6 +275,16 @@ public class Ant extends Task {
     }
 
     /**
+     * Process input into the ant task
+     *
+     * @param buffer the buffer into which data is to be read.
+     * @param offset the offset into the buffer at which data is stored.
+     * @param length the amount of data to read
+     *
+     * @return the number of bytes read
+     *
+     * @exception IOException if the data cannot be read
+     *
      * @see Task#handleInput(byte[], int, int)
      *
      * @since Ant 1.6
@@ -288,6 +301,8 @@ public class Ant extends Task {
     /**
      * Pass output sent to System.out to the new project.
      *
+     * @param output The output to log. Should not be <code>null</code>.
+     *
      * @since Ant 1.5.2
      */
     public void handleFlush(String output) {
@@ -301,6 +316,8 @@ public class Ant extends Task {
     /**
      * Pass output sent to System.err to the new project.
      *
+     * @param output The error output to log. Should not be <code>null</code>.
+     *
      * @since Ant 1.5
      */
     public void handleErrorOutput(String output) {
@@ -314,6 +331,8 @@ public class Ant extends Task {
     /**
      * Pass output sent to System.err to the new project.
      *
+     * @param output The error output to log. Should not be <code>null</code>.
+     *
      * @since Ant 1.5.2
      */
     public void handleErrorFlush(String output) {
@@ -326,6 +345,8 @@ public class Ant extends Task {
 
     /**
      * Do the execution.
+     * @throws BuildException if a target tries to call itself
+     * probably also if a BuildException is thrown by the new project
      */
     public void execute() throws BuildException {
         File savedDir = dir;
@@ -414,6 +435,7 @@ public class Ant extends Task {
     /**
      * Override the properties in the new project with the one
      * explicitly defined as nested elements here.
+     * @throws BuildException under unknown circumstances
      */
     private void overrideProperties() throws BuildException {
         Enumeration e = properties.elements();
@@ -430,6 +452,7 @@ public class Ant extends Task {
      * new project.  Also copy over all references that don't override
      * existing references in the new project if inheritrefs has been
      * requested.
+     * @throws BuildException if a reference does not have a refid
      */
     private void addReferences() throws BuildException {
         Hashtable thisReferences
@@ -528,7 +551,7 @@ public class Ant extends Task {
      * Copies all properties from the given table to the new project -
      * ommiting those that have already been set in the new project as
      * well as properties named basedir or ant.file.
-     *
+     * @param props properties to copy to the new project
      * @since Ant 1.6
      */
     private void addAlmostAll(Hashtable props) {
@@ -554,6 +577,7 @@ public class Ant extends Task {
      * Defaults to the current project's basedir, unless inheritall
      * has been set to false, in which case it doesn't have a default
      * value. This will override the basedir setting of the called project.
+     * @param d new directory
      */
     public void setDir(File d) {
         this.dir = d;
@@ -563,6 +587,7 @@ public class Ant extends Task {
      * The build file to use.
      * Defaults to "build.xml". This file is expected to be a filename relative
      * to the dir attribute given.
+     * @param s build file to use
      */
     public void setAntfile(String s) {
         // @note: it is a string and not a file to handle relative/absolute
@@ -574,6 +599,7 @@ public class Ant extends Task {
     /**
      * The target of the new Ant project to execute.
      * Defaults to the new project's default target.
+     * @param s target to invoke
      */
     public void setTarget(String s) {
         if (s.equals("")) {
@@ -588,6 +614,7 @@ public class Ant extends Task {
      * This is relative to the value of the dir attribute
      * if it has been set or to the base directory of the
      * current project otherwise.
+     * @param s file to which the output should go to
      */
     public void setOutput(String s) {
         this.output = s;
@@ -596,6 +623,7 @@ public class Ant extends Task {
     /**
      * Property to pass to the new project.
      * The property is passed as a 'user property'
+     * @return new property created
      */
     public Property createProperty() {
         if (newProject == null) {
@@ -611,6 +639,7 @@ public class Ant extends Task {
     /**
      * Reference element identifying a data type to carry
      * over to the new project.
+     * @param r reference to add
      */
     public void addReference(Reference r) {
         references.addElement(r);
@@ -619,6 +648,7 @@ public class Ant extends Task {
     /**
      * Set of properties to pass to the new project.
      *
+     * @param ps property set to add
      * @since Ant 1.6
      */
     public void addPropertyset(PropertySet ps) {

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

@@ -96,6 +96,7 @@ public class AntStructure extends Task {
 
     /**
      * The output file.
+     * @param output the output file
      */
     public void setOutput(File output) {
         this.output = output;
@@ -358,6 +359,8 @@ public class AntStructure extends Task {
 
     /**
      * Does this String match the XML-NMTOKEN production?
+     * @param s the string to test
+     * @return true if the string matche the XML-NMTOKEN
      */
     protected boolean isNmtoken(String s) {
         final int length = s.length();
@@ -377,6 +380,8 @@ public class AntStructure extends Task {
      *
      * <p>Otherwise they are not suitable as an enumerated attribute,
      * for example.</p>
+     * @param s the array of string to test
+     * @return true if all the strings in the array math XML-NMTOKEN
      */
     protected boolean areNmtokens(String[] s) {
         for (int i = 0; i < s.length; i++) {

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

@@ -202,6 +202,7 @@ public class Available extends Task implements Condition {
      *             setType(Available.FileDir) to make Ant's Introspection
      *             mechanism do the work and also to encapsulate operations on
      *             the type in its own class.
+     * @param type the type of resource
      */
     public void setType(String type) {
         log("DEPRECATED - The setType(String) method has been deprecated."
@@ -510,13 +511,13 @@ public class Available extends Task implements Condition {
      */
     public static class FileDir extends EnumeratedAttribute {
 
-        private static final String[] values = {"file", "dir"};
+        private static final String[] VALUES = {"file", "dir"};
 
         /**
          * @see EnumeratedAttribute#getValues
          */
         public String[] getValues() {
-            return values;
+            return VALUES;
         }
 
         /**

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

@@ -95,14 +95,16 @@ public class Basename extends Task {
     private String suffix;
 
     /**
-    * File or directory to get base name from.
-    */
+     * file or directory to get base name from
+     * @param file file or directory to get base name from
+     */
     public void setFile(File file) {
         this.file = file;
     }
 
     /**
     * Property to set base name to.
+     * @param property name of property
     */
     public void setProperty(String property) {
         this.property  = property;
@@ -110,13 +112,17 @@ public class Basename extends Task {
 
     /**
     * Optional suffix to remove from base name.
+     * @param suffix suffix to remove from base name
     */
     public void setSuffix(String suffix) {
         this.suffix = suffix;
     }
 
-
-    // The method executing the task
+    /**
+     * do the work
+     * @throws BuildException if required attributes are not supplied
+     * property and attribute are required attributes
+     */
     public void execute() throws BuildException {
         if (property == null) {
             throw new BuildException("property attribute required", getLocation());

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

@@ -1,7 +1,7 @@
 /*
  * The Apache Software License, Version 1.1
  *
- * Copyright (c) 2002 The Apache Software Foundation.  All rights
+ * Copyright (c) 2002-2003 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -60,6 +60,7 @@ import java.io.IOException;
 import java.util.Properties;
 import org.apache.tools.ant.BuildException;
 import org.apache.tools.ant.Task;
+import org.apache.tools.ant.Project;
 import org.apache.tools.ant.util.FileUtils;
 
 /**
@@ -86,7 +87,7 @@ public class BuildNumber
     private static final String DEFAULT_FILENAME = DEFAULT_PROPERTY_NAME;
 
     /** The File in which the build number is stored.  */
-    private File m_file;
+    private File myFile;
 
 
     /**
@@ -96,7 +97,7 @@ public class BuildNumber
      * @param file the file in which build number is stored.
      */
     public void setFile(final File file) {
-        m_file = file;
+        myFile = file;
     }
 
 
@@ -107,7 +108,7 @@ public class BuildNumber
      */
     public void execute()
          throws BuildException {
-        File savedFile = m_file; // may be altered in validate
+        File savedFile = myFile; // may be altered in validate
 
         validate();
 
@@ -121,13 +122,13 @@ public class BuildNumber
         FileOutputStream output = null;
 
         try {
-            output = new FileOutputStream(m_file);
+            output = new FileOutputStream(myFile);
 
             final String header = "Build Number for ANT. Do not edit!";
 
             properties.save(output, header);
         } catch (final IOException ioe) {
-            final String message = "Error while writing " + m_file;
+            final String message = "Error while writing " + myFile;
 
             throw new BuildException(message, ioe);
         } finally {
@@ -135,9 +136,10 @@ public class BuildNumber
                 try {
                     output.close();
                 } catch (final IOException ioe) {
+                    getProject().log("error closing output stream " + ioe, Project.MSG_ERR);
                 }
             }
-            m_file = savedFile;
+            myFile = savedFile;
         }
 
         //Finally set the property
@@ -163,7 +165,7 @@ public class BuildNumber
             return Integer.parseInt(buildNumber);
         } catch (final NumberFormatException nfe) {
             final String message =
-                m_file + " contains a non integer build number: " + buildNumber;
+                myFile + " contains a non integer build number: " + buildNumber;
 
             throw new BuildException(message, nfe);
         }
@@ -183,7 +185,7 @@ public class BuildNumber
         try {
             final Properties properties = new Properties();
 
-            input = new FileInputStream(m_file);
+            input = new FileInputStream(myFile);
             properties.load(input);
             return properties;
         } catch (final IOException ioe) {
@@ -193,6 +195,7 @@ public class BuildNumber
                 try {
                     input.close();
                 } catch (final IOException ioe) {
+                    getProject().log("error closing input stream " + ioe, Project.MSG_ERR);
                 }
             }
         }
@@ -206,29 +209,29 @@ public class BuildNumber
      */
     private void validate()
          throws BuildException {
-        if (null == m_file) {
-            m_file = getProject().resolveFile(DEFAULT_FILENAME);
+        if (null == myFile) {
+            myFile = getProject().resolveFile(DEFAULT_FILENAME);
         }
 
-        if (!m_file.exists()) {
+        if (!myFile.exists()) {
             try {
-                FileUtils.newFileUtils().createNewFile(m_file);
+                FileUtils.newFileUtils().createNewFile(myFile);
             } catch (final IOException ioe) {
                 final String message =
-                    m_file + " doesn't exist and new file can't be created.";
+                    myFile + " doesn't exist and new file can't be created.";
 
                 throw new BuildException(message, ioe);
             }
         }
 
-        if (!m_file.canRead()) {
-            final String message = "Unable to read from " + m_file + ".";
+        if (!myFile.canRead()) {
+            final String message = "Unable to read from " + myFile + ".";
 
             throw new BuildException(message);
         }
 
-        if (!m_file.canWrite()) {
-            final String message = "Unable to write to " + m_file + ".";
+        if (!myFile.canWrite()) {
+            final String message = "Unable to write to " + myFile + ".";
 
             throw new BuildException(message);
         }