JavaDoc comments.

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

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

@@ -115,7 +115,7 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
         private URL nextResource;
 
         /**
-         * Construct a new enumeration of resources of the given name found
+         * Constructs a new enumeration of resources of the given name found
          * within this class loader's classpath.
          *
          * @param name the name of the resource to search for.
@@ -140,7 +140,7 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
         /**
          * Returns the next resource in the enumeration.
          *
-         * @return the next resource in the enumeration.
+         * @return the next resource in the enumeration
          */
         public Object nextElement() {
             URL ret = this.nextResource;
@@ -211,19 +211,20 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     private Vector loaderPackages = new Vector();
 
     /**
-     * This flag indicates that the classloader will ignore the base
-     * classloader if it can't find a class. This is set by the
-     * {@link #setIsolated(boolean) setIsolated} method.
+     * Whether or not this classloader will ignore the base
+     * classloader if it can't find a class.
+     *
+     * @see #setIsolated(boolean)
      */
     private boolean ignoreBase = false;
 
     /**
-     * The parent class loader, if one is given or can be determined
+     * The parent class loader, if one is given or can be determined.
      */
     private ClassLoader parent = null;
 
     /**
-     * A hashtable of zip files opened by the classloader (File to ZipFile)
+     * A hashtable of zip files opened by the classloader (File to ZipFile).
      */
     private Hashtable zipFiles = new Hashtable();
 
@@ -277,11 +278,11 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
 
 
     /**
-     * Create a classloader for the given project using the classpath given.
+     * Creates a classloader for the given project using the classpath given.
      *
-     * @param project the project to which this classloader is to belong.
+     * @param project The project to which this classloader is to belong.
      *                Must not be <code>null</code>.
-     * @param classpath the classpath to use to load the classes.  This
+     * @param classpath The classpath to use to load the classes.  This
      *                is combined with the system classpath in a manner
      *                determined by the value of ${build.sysclasspath}.
      *                May be <code>null</code>, in which case no path
@@ -306,20 +307,20 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Create a classloader for the given project using the classpath given.
+     * Creates a classloader for the given project using the classpath given.
      *
-     * @param parent the parent classloader to which unsatisfied loading 
+     * @param parent The parent classloader to which unsatisfied loading 
      *               attempts are delegated. May be <code>null</code>,
      *               in which case the classloader which loaded this
      *               class is used as the parent.
-     * @param project the project to which this classloader is to belong.
+     * @param project The project to which this classloader is to belong.
      *                Must not be <code>null</code>.
      * @param classpath the classpath to use to load the classes.
      *                  May be <code>null</code>, in which case no path
      *                  elements are set up to start with.
-     * @param parentFirst if <code>true</code> indicates that the parent 
-     *                    classloader should be consulted  before trying to load 
-     *                    the a class through this loader.
+     * @param parentFirst If <code>true</code>, indicates that the parent 
+     *                    classloader should be consulted  before trying to
+     *                    load the a class through this loader.
      */
     public AntClassLoader(ClassLoader parent, Project project, Path classpath,
                           boolean parentFirst) {
@@ -334,15 +335,14 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
 
 
     /**
-     * Create a classloader for the given project using the classpath given.
+     * Creates a classloader for the given project using the classpath given.
      *
-     * @param project the project to which this classloader is to belong.
+     * @param project The project to which this classloader is to belong.
      *                Must not be <code>null</code>.
-     * @param classpath the classpath to use to load the classes. May be 
+     * @param classpath The classpath to use to load the classes. May be 
      *                  <code>null</code>, in which case no path
      *                  elements are set up to start with.
-     *                
-     * @param parentFirst if <code>true</code> indicates that the parent 
+     * @param parentFirst If <code>true</code>, indicates that the parent 
      *                    classloader should be consulted before trying to 
      *                    load the a class through this loader.
      */
@@ -351,16 +351,16 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Create an empty class loader. The classloader should be configured 
+     * Creates an empty class loader. The classloader should be configured
      * with path elements to specify where the loader is to look for 
      * classes.
      *
-     * @param parent the parent classloader to which unsatisfied loading 
+     * @param parent The parent classloader to which unsatisfied loading 
      *               attempts are delegated. May be <code>null</code>,
      *               in which case the classloader which loaded this
      *               class is used as the parent.
-     * @param parentFirst if <code>true</code> indicates that the parent 
-     *                    classloader should be consulted before trying to 
+     * @param parentFirst If <code>true</code>, indicates that the parent 
+     *                    classloader should be consulted before trying to
      *                    load the a class through this loader.
      */
     public AntClassLoader(ClassLoader parent, boolean parentFirst) {
@@ -375,10 +375,12 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Log a message through the project object if one has been provided.
+     * Logs a message through the project object if one has been provided.
      *
-     * @param message the message to log
-     * @param priority the logging priority of the message
+     * @param message The message to log. 
+     *                Should not be <code>null</code>.
+     *                
+     * @param priority The logging priority of the message.
      */
     protected void log(String message, int priority) {
         if (project != null) {
@@ -390,7 +392,7 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Set the current thread's context loader to this classloader, storing
+     * Sets the current thread's context loader to this classloader, storing
      * the current loader value for later resetting.
      */
     public void setThreadContextLoader() {
@@ -416,7 +418,7 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Reset the current thread's context loader to its original value.
+     * Resets the current thread's context loader to its original value.
      */
     public void resetThreadContextLoader() {
         if (isContextLoaderSaved &&
@@ -439,10 +441,13 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
 
 
     /**
-     * Add an element to the classpath to be searched.
+     * Adds an element to the classpath to be searched.
      *
-     * @param pathElement the path element to add. Must not be 
+     * @param pathElement The path element to add. Must not be 
      *                    <code>null</code>.
+     * 
+     * @exception BuildException if the given path element cannot be resolved
+     *                           against the project.
      */
     public void addPathElement(String pathElement) throws BuildException {
         File pathComponent
@@ -452,12 +457,12 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Get the CLASSPATH this classloader will consult.
+     * Returns the classpath this classloader will consult.
      * 
      * @return the classpath used for this classloader, with elements 
      *         separated by the path separator for the system.
      */
-    public String getClasspath() {
+    public String getClasspath(){
         StringBuffer sb = new StringBuffer();
         boolean firstPass = true;
         Enumeration enum = pathComponents.elements();
@@ -473,23 +478,24 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Set whether this classloader should run in isolated mode. In 
+     * Sets whether this classloader should run in isolated mode. In 
      * isolated mode, classes not found on the given classpath will 
      * not be referred to the parent class loader but will cause a 
      * ClassNotFoundException.
      * 
-     * @param isolated whether this classloader should run in isolated mode 
-     * or not.
+     * @param isolated Whether or not this classloader should run in 
+     *                 isolated mode.
      */
     public void setIsolated(boolean isolated) {
         ignoreBase = isolated;
     }
 
     /**
-     * Force initialization of a class in a JDK 1.1 compatible, albeit hacky
+     * Forces initialization of a class in a JDK 1.1 compatible, albeit hacky
      * way.
      * 
-     * @param theClass the class to initialize. Must not be <code>null</code>.
+     * @param theClass The class to initialize. 
+     *                 Must not be <code>null</code>.
      */
     public static void initializeClass(Class theClass) {
         // ***HACK*** We ask the VM to create an instance
@@ -525,44 +531,45 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Add a package root to the list of packages which must be loaded on the
+     * Adds a package root to the list of packages which must be loaded on the
      * parent loader.
      * 
      * All subpackages are also included.
      *
-     * @param packageRoot the root of all packages to be included. Should not
-     *                    be <code>null</code>.
+     * @param packageRoot The root of all packages to be included.
+     *                    Should not be <code>null</code>.
      */
     public void addSystemPackageRoot(String packageRoot) {
         systemPackages.addElement(packageRoot + ".");
     }
 
     /**
-     * Add a package root to the list of packages which must be loaded using
+     * Adds a package root to the list of packages which must be loaded using
      * this loader.
      * 
      * All subpackages are also included.
      *
-     * @param packageRoot the root of all packages to be included. Should not
-     *                    be <code>null</code>.
+     * @param packageRoot The root of all packages to be included. 
+     *                    Should not be <code>null</code>.
      */
     public void addLoaderPackageRoot(String packageRoot) {
         loaderPackages.addElement(packageRoot + ".");
     }
 
     /**
-     * Load a class through this class loader even if that class is available 
+     * Loads a class through this class loader even if that class is available
      * on the parent classpath.
      * 
      * This ensures that any classes which are loaded by the returned class 
      * will use this classloader.
      *
-     * @param classname the classname to be loaded. Must not be <code>null</code>.
+     * @param classname The name of the class to be loaded. 
+     *                  Must not be <code>null</code>.
      *
      * @return the required Class object
      *
      * @exception ClassNotFoundException if the requested class does not exist
-     * on this loader's classpath.
+     *                                   on this loader's classpath.
      */
     public Class forceLoadClass(String classname) throws ClassNotFoundException {
         log("force loading " + classname, Project.MSG_DEBUG);
@@ -577,15 +584,15 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Load a class through this class loader but defer to the parent class 
+     * Loads a class through this class loader but defer to the parent class
      * loader.
      * 
      * This ensures that instances of the returned class will be compatible 
      * with instances which which have already been loaded on the parent 
      * loader.
      *
-     * @param classname the classname to be loaded. Must not be 
-     * <code>null</code>.
+     * @param classname The name of the class to be loaded. 
+     *                  Must not be <code>null</code>.
      *
      * @return the required Class object
      *
@@ -605,9 +612,9 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Get a stream to read the requested resource name.
+     * Returns a stream to read the requested resource name.
      *
-     * @param name the name of the resource for which a stream is required.
+     * @param name The name of the resource for which a stream is required.
      *             Must not be <code>null</code>.
      *
      * @return a stream to the required resource or <code>null</code> if the 
@@ -654,9 +661,9 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Get a stream to read the requested resource name from this loader.
+     * Returns a stream to read the requested resource name from this loader.
      *
-     * @param name the name of the resource for which a stream is required.
+     * @param name The name of the resource for which a stream is required.
      *             Must not be <code>null</code>.
      *
      * @return a stream to the required resource or <code>null</code> if 
@@ -675,14 +682,14 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Find a system resource (which should be loaded from the parent 
+     * Finds a system resource (which should be loaded from the parent 
      * classloader).
      * 
-     * @param name the name of the system resource to load. Must not be
-     *             <code>null</code>.
+     * @param name The name of the system resource to load. 
+     *             Must not be <code>null</code>.
      * 
      * @return a stream to the named resource, or <code>null</code> if
-     * the resource cannot be found.
+     *         the resource cannot be found.
      */
     private InputStream loadBaseResource(String name) {
         if (parent == null) {
@@ -694,16 +701,16 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Get an inputstream to a given resource in the given file which may
+     * Returns an inputstream to a given resource in the given file which may
      * either be a directory or a zip file.
      *
      * @param file the file (directory or jar) in which to search for the 
      *             resource. Must not be <code>null</code>.
-     * @param resourceName the name of the resource for which a stream is 
+     * @param resourceName The name of the resource for which a stream is 
      *                     required. Must not be <code>null</code>.
      *
      * @return a stream to the required resource or <code>null</code> if 
-     * the resource cannot be found in the given file.
+     *         the resource cannot be found in the given file.
      */
     private InputStream getResourceStream(File file, String resourceName) {
         try {
@@ -740,16 +747,16 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Get whether or not the parent classloader should be checked for
+     * Tests whether or not the parent classloader should be checked for
      * a resource before this one. If the resource matches both the
-     * "use parent classloader first" and the "use this classloader first" 
+     * "use parent classloader first" and the "use this classloader first"
      * lists, the latter takes priority.
      * 
-     * @param resourceName the name of the resource to check. Must not be
-     *                     <code>null</code>.
+     * @param resourceName The name of the resource to check.
+     *                     Must not be <code>null</code>.
      * 
      * @return whether or not the parent classloader should be checked for a 
-     * resource before this one is.
+     *         resource before this one is.
      */
     private boolean isParentFirst(String resourceName) {
         // default to the global setting and then see
@@ -784,7 +791,7 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
      * some data (images, audio, text, etc) that can be accessed by class
      * code in a way that is independent of the location of the code.
      *
-     * @param name the name of the resource for which a stream is required.
+     * @param name The name of the resource for which a stream is required.
      *             Must not be <code>null</code>.
      *
      * @return a URL for reading the resource, or <code>null</code> if the 
@@ -838,9 +845,9 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
      * Returns an enumeration of URLs representing all the resources with the
      * given name by searching the class loader's classpath.
      *
-     * @param name the resource name to search for. Must not be 
-     *             <code>null</code>.
-     * @return an enumeration of URLs for the resources.
+     * @param name The resource name to search for. 
+     *             Must not be <code>null</code>.
+     * @return an enumeration of URLs for the resources
      * @exception IOException if I/O errors occurs (can't happen)
      */
     protected Enumeration findResources(String name) throws IOException {
@@ -848,16 +855,16 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Get an inputstream to a given resource in the given file which may
+     * Returns an inputstream to a given resource in the given file which may
      * either be a directory or a zip file.
      *
-     * @param file the file (directory or jar) in which to search for
+     * @param file The file (directory or jar) in which to search for
      *             the resource. Must not be <code>null</code>.
-     * @param resourceName the name of the resource for which a stream
+     * @param resourceName The name of the resource for which a stream
      *                     is required. Must not be <code>null</code>.
      *
      * @return a stream to the required resource or <code>null</code> if the
-     *         resource cannot be found in the given file object
+     *         resource cannot be found in the given file object.
      */
     private URL getResourceURL(File file, String resourceName) {
         try {
@@ -901,7 +908,7 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Load a class with this class loader.
+     * Loads a class with this class loader.
      *
      * This class attempts to load the class in an order determined by whether
      * or not the class matches the system/loader package lists, with the 
@@ -909,7 +916,7 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
      * mode, failure to load the class in this loader will result in a 
      * ClassNotFoundException.
      *
-     * @param classname the name of the class to be loaded. 
+     * @param classname The name of the class to be loaded. 
      *                  Must not be <code>null</code>.
      * @param resolve <code>true</code> if all classes upon which this class 
      *                depends are to be loaded.
@@ -959,10 +966,10 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Convert the class dot notation to a filesystem equivalent for
+     * Converts the class dot notation to a filesystem equivalent for
      * searching purposes.
      *
-     * @param classname the class name in dot format (eg java.lang.Integer).
+     * @param classname The class name in dot format (eg java.lang.Integer).
      *                  Must not be <code>null</code>.
      *
      * @return the classname in filesystem format (eg java/lang/Integer.class)
@@ -972,12 +979,12 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Read a class definition from a stream.
+     * Reads a class definition from a stream.
      *
-     * @param stream the stream from which the class is to be read.
-     *               Must not be <code>null</code>.
-     * @param classname the class name of the class in the stream.
+     * @param stream The stream from which the class is to be read.
      *               Must not be <code>null</code>.
+     * @param classname The name of the class in the stream.
+     *                  Must not be <code>null</code>.
      *
      * @return the Class object read from the stream.
      *
@@ -1027,15 +1034,15 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Search for and load a class on the classpath of this class loader.
+     * Searches for and load a class on the classpath of this class loader.
      *
-     * @param name the name of the class to be loaded. Must not be 
+     * @param name The name of the class to be loaded. Must not be 
      *             <code>null</code>.
      *
      * @return the required Class object
      *
      * @exception ClassNotFoundException if the requested class does not exist
-     * on this loader's classpath.
+     *                                   on this loader's classpath.
      */
     public Class findClass(String name) throws ClassNotFoundException {
         log("Finding class " + name, Project.MSG_DEBUG);
@@ -1045,9 +1052,9 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
 
 
     /**
-     * Find a class on the given classpath.
+     * Finds a class on the given classpath.
      * 
-     * @param name the name of the class to be loaded. Must not be 
+     * @param name The name of the class to be loaded. Must not be 
      *             <code>null</code>.
      * 
      * @return the required Class object
@@ -1088,14 +1095,14 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Find a system class (which should be loaded from the same classloader 
+     * Finds a system class (which should be loaded from the same classloader
      * as the Ant core).
      * 
      * For JDK 1.1 compatability, this uses the findSystemClass method if
      * no parent classloader has been specified.
      * 
-     * @param name the name of the class to be loaded. Must not be 
-     *             <code>null</code>.
+     * @param name The name of the class to be loaded. 
+     *             Must not be <code>null</code>.
      * 
      * @return the required Class object
      *
@@ -1112,7 +1119,7 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Clean up any resources held by this classloader. Any open archive
+     * Cleans up any resources held by this classloader. Any open archive
      * files are closed.
      */
     public void cleanup() {
@@ -1137,7 +1144,7 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
     }
 
     /**
-     * Clean up any resources held by this classloader at the end
+     * Cleans up any resources held by this classloader at the end
      * of a build.
      */
     public void buildFinished(BuildEvent event) {

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

@@ -70,46 +70,47 @@ import java.util.Hashtable;
 public class DemuxOutputStream extends OutputStream {
 
     /**
-     * A data class to store information about a buffer. Such informatio
+     * A data class to store information about a buffer. Such information
      * is stored on a per-thread basis.
      */
     private static class BufferInfo {
         /**
-         * The per-thread output stream
+         * The per-thread output stream.
          */
         private ByteArrayOutputStream buffer;
         
         /** 
-         * Whether the next line-terminator should be skipped in terms
-         * of processing the buffer or not. Used to avoid \r\n invoking
+         * Whether or not the next line-terminator should be skipped in terms
+         * of processing the buffer. Used to avoid \r\n invoking
          * processBuffer twice.
          */
          private boolean skip = false;
     }
     
-    /** Maximum buffer size */
+    /** Maximum buffer size. */
     private final static int MAX_SIZE = 1024;
-    /** Mapping from thread to buffer (Thread to BufferInfo) */
+    /** Mapping from thread to buffer (Thread to BufferInfo). */
     private Hashtable buffers = new Hashtable();
 
     /**
-     * The project to send output to
+     * The project to send output to.
      */
     private Project project;
 
     /**
-     * Whether or not this stream represents an error stream
+     * Whether or not this stream represents an error stream.
      */
     private boolean isErrorStream;
     
     /**
      * Creates a new instance of this class.
      *
-     * @param project the project instance for which output is being 
-     * demultiplexed.
-     * @param isErrorStream true if this is the error string, otherwise 
-     * a normal output stream. This is passed to the project so it knows
-     * which stream it is receiving.
+     * @param project The project instance for which output is being 
+     *                demultiplexed. Must not be <code>null</code>.
+     * @param isErrorStream <code>true</code> if this is the error string, 
+     *                      otherwise a normal output stream. This is 
+     *                      passed to the project so it knows
+     *                      which stream it is receiving.
      */
     public DemuxOutputStream(Project project, boolean isErrorStream) {
         this.project = project;
@@ -119,7 +120,7 @@ public class DemuxOutputStream extends OutputStream {
     /**
      * Returns the buffer associated with the current thread.
      * 
-     * @return a ByteArrayOutputStream for the current thread to write data to
+     * @return a BufferInfo for the current thread to write data to
      */
     private BufferInfo getBufferInfo() {
         Thread current = Thread.currentThread();
@@ -165,13 +166,13 @@ public class DemuxOutputStream extends OutputStream {
         bufferInfo.skip = (c == '\r');
     }
 
-
     /**
-     * Converts the buffer to a string and sends it to 
-     * {@link Project#demuxOutput(String,boolean) Project.demuxOutput}.
+     * Converts the buffer to a string and sends it to the project.
      *
      * @param buffer the ByteArrayOutputStream used to collect the output
      * until a line separator is seen.
+     * 
+     * @see Project#demuxOutput(String,boolean)
      */
     protected void processBuffer(ByteArrayOutputStream buffer) {
         String output = buffer.toString();
@@ -180,9 +181,11 @@ public class DemuxOutputStream extends OutputStream {
     }
 
     /**
-     * Equivalent to calling {@link #flush flush} on the stream.
+     * Equivalent to flushing the stream.
      *
      * @exception IOException if there is a problem closing the stream.
+     * 
+     * @see #flush
      */
     public void close() throws IOException {
         flush();

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

@@ -384,6 +384,10 @@ public class IntrospectionHelper implements BuildListener {
      * @param value The value to set the attribute to. This may be interpreted
      *              or converted to the necessary type if the setter method
      *              doesn't just take a string. Must not be <code>null</code>.
+     * 
+     * @exception BuildException if the introspected class doesn't support 
+     *                           the given attribute, or if the setting 
+     *                           method fails.
      */
     public void setAttribute(Project p, Object element, String attributeName,
                              String value)

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

@@ -1,7 +1,7 @@
 /*
  * The Apache Software License, Version 1.1
  *
- * Copyright (c) 2000 The Apache Software Foundation.  All rights
+ * Copyright (c) 2000,2002 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -55,13 +55,20 @@
 package org.apache.tools.ant;
 
 /**
- * Stores the file name and line number in a file.
+ * Stores the location of a piece of text within a file (file name,
+ * line number and column number). Note that the column number is
+ * currently ignored.
  */
 public class Location {
+    
+    /** Name of the file. */
     private String fileName;
+    /** Line number within the file. */
     private int lineNumber;
+    /** Column number within the file. */
     private int columnNumber;
 
+    /** Location to use when one is needed but no information is available */
     public final static Location UNKNOWN_LOCATION = new Location();
 
     /**
@@ -72,14 +79,28 @@ public class Location {
     }
 
     /**
-     * Creates a location consisting of a file name but no line number.
+     * Creates a location consisting of a file name but no line number or
+     * column number.
+     * 
+     * @param fileName The name of the file. May be <code>null</code>,
+     *                 in which case the location is equivalent to
+     *                 {@link #UNKNOWN_LOCATION UNKNOWN_LOCATION}.
      */
     public Location(String fileName) {
         this(fileName, 0, 0);
     }
 
     /**
-     * Creates a location consisting of a file name and line number.
+     * Creates a location consisting of a file name, line number and
+     * column number.
+     * 
+     * @param fileName The name of the file. May be <code>null</code>,
+     *                 in which case the location is equivalent to
+     *                 {@link #UNKNOWN_LOCATION UNKNOWN_LOCATION}.
+     * 
+     * @param lineNumber Line number within the file. Use 0 for unknown
+     *                   positions within a file.
+     * @param columnNumber Column number within the line.
      */
     public Location(String fileName, int lineNumber, int columnNumber) {
         this.fileName = fileName;
@@ -88,9 +109,14 @@ public class Location {
     }
 
     /**
-     * Returns the file name, line number and a trailing space. An error
-     * message can be appended easily. For unknown locations, returns
-     * an empty string.
+     * Returns the file name, line number, a colon and a trailing space. 
+     * An error message can be appended easily. For unknown locations, an 
+     * empty string is returned.
+     * 
+     * @return a String of the form <code>"fileName: lineNumber: "</code>
+     *         if both file name and line number are known,
+     *         <code>"fileName: "</code> if only the file name is known,
+     *         and the empty string for unknown locations.
      */
     public String toString() {
         StringBuffer buf = new StringBuffer();

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

@@ -78,57 +78,63 @@ import java.util.Enumeration;
  */
 public class Main {
 
-    /** The default build file name */
+    /** The default build file name. */
     public final static String DEFAULT_BUILD_FILENAME = "build.xml";
 
-    /** Our current message output status. Follows Project.MSG_XXX */
+    /** Our current message output status. Follows Project.MSG_XXX. */
     private int msgOutputLevel = Project.MSG_INFO;
 
-    /** File that we are using for configuration */
-    private File buildFile; /** null */
+    /** File that we are using for configuration. */
+    private File buildFile; /* null */
 
-    /** Stream that we are using for logging */
+    /** Stream to use for logging. */
     private PrintStream out = System.out;
 
-    /** Stream that we are using for logging error messages */
+    /** Stream that we are using for logging error messages. */
     private PrintStream err = System.err;
 
-    /** The build targets */
+    /** The build targets. */
     private Vector targets = new Vector(5);
 
-    /** Set of properties that can be used by tasks */
+    /** Set of properties that can be used by tasks. */
     private Properties definedProps = new Properties();
 
-    /** Names of classes to add as listeners to project */
+    /** Names of classes to add as listeners to project. */
     private Vector listeners = new Vector(5);
     
-    /** File names of property files to load on startup */
+    /** File names of property files to load on startup. */
     private Vector propertyFiles = new Vector(5);
-
+    
     /**
-     * The Ant logger class. There may be only one logger. It will have the
-     * right to use the 'out' PrintStream. The class must implements the BuildLogger
-     * interface
+     * The Ant logger class. There may be only one logger. It will have 
+     * the right to use the 'out' PrintStream. The class must implements the 
+     * BuildLogger interface.
      */
     private String loggerClassname = null;
 
     /**
-     * Indicates whether output to the log is to be unadorned.
+     * Whether or not output to the log is to be unadorned.
      */
     private boolean emacsMode = false;
 
     /**
-     * Indicates if this ant should be run.
+     * Whether or not this instance has successfully been
+     * constructed and is ready to run.
      */
     private boolean readyToRun = false;
 
     /**
-     * Indicates we should only parse and display the project help information
+     * Whether or not we should only parse and display the project help 
+     * information.
      */
     private boolean projectHelp = false;
 
     /**
-     * Prints the message of the Throwable if it's not null.
+     * Prints the message of the Throwable if it (the message) is not 
+     * <code>null</code>.
+     * 
+     * @param t Throwable to print the message of.
+     *          Must not be <code>null</code>.
      */
     private static void printMessage(Throwable t) {
         String message = t.getMessage();
@@ -138,7 +144,16 @@ public class Main {
     }
 
     /**
-     * Entry point method.
+     * Creates a new instance of this class using the
+     * arguments specified, gives it any extra user properties which have been
+     * specified, and then runs the build using the classloader provided.
+     * 
+     * @param args Command line arguments. Must not be <code>null</code>.
+     * @param additionalUserProperties Any extra properties to use in this 
+     *        build. May be <code>null</code>, which is the equivalent to 
+     *        passing in an empty set of properties.
+     * @param coreLoader Classloader used for core classes. May be 
+     *        <code>null</code> in which case the system classloader is used.
      */
     public static void start(String[] args, Properties additionalUserProperties,
                              ClassLoader coreLoader) {
@@ -173,20 +188,31 @@ public class Main {
             System.exit(1);
         }
     }
-                                 
-    
-    
+                                        
     /**
      * Command line entry point. This method kicks off the building
      * of a project object and executes a build using either a given
      * target or the default target.
      *
-     * @param args Command line args.
+     * @param args Command line arguments. Must not be <code>null</code>.
      */
     public static void main(String[] args) {
         start(args, null, null);
     }
 
+    // XXX: (Jon Skeet) Error handling appears to be inconsistent here.
+    // Sometimes there's just a return statement, and sometimes a
+    // BuildException is thrown. What's the rationale for when to do
+    // what?
+    /**
+     * Sole constructor, which parses and deals with command line 
+     * arguments.
+     * 
+     * @param args Command line arguments. Must not be <code>null</code>.
+     * 
+     * @exception BuildException if the specified build file doesn't exist
+     *                           or is a directory.
+     */
     protected Main(String[] args) throws BuildException {
 
         String searchForThis = null;
@@ -253,7 +279,7 @@ public class Main {
 
                 /* Interestingly enough, we get to here when a user
                  * uses -Dname=value. However, in some cases, the JDK
-                 * goes ahead * and parses this out to args
+                 * goes ahead and parses this out to args
                  *   {"-Dname", "value"}
                  * so instead of parsing on "=", we just make the "-D"
                  * characters go away and skip one argument forward.
@@ -383,10 +409,10 @@ public class Main {
 
     /**
      * Helper to get the parent file for a given file.
+     * <p>
+     * Added to simulate File.getParentFile() from JDK 1.2.
      *
-     * <P>Added to simulate File.getParentFile() from JDK 1.2.
-     *
-     * @param file   File
+     * @param file   File to find parent of. Must not be <code>null</code>.
      * @return       Parent file or null if none
      */
     private File getParentFile(File file) {
@@ -403,16 +429,20 @@ public class Main {
 
     /**
      * Search parent directories for the build file.
+     * <p>
+     * Takes the given target as a suffix to append to each
+     * parent directory in seach of a build file.  Once the
+     * root of the file-system has been reached an exception
+     * is thrown.
      *
-     * <P>Takes the given target as a suffix to append to each
-     *    parent directory in seach of a build file.  Once the
-     *    root of the file-system has been reached an exception
-     *    is thrown.
-     *
-     * @param suffix    Suffix filename to look for in parents.
-     * @return          A handle to the build file
+     * @param start  Leaf directory of search.
+     *               Must not be <code>null</code>.
+     * @param suffix  Suffix filename to look for in parents.
+     *                Must not be <code>null</code>.
+     * 
+     * @return A handle to the build file if one is found
      *
-     * @exception BuildException    Failed to locate a build file
+     * @exception BuildException if no build file is found
      */
     private File findBuildFile(String start, String suffix) throws BuildException {
         if (msgOutputLevel >= Project.MSG_INFO) {
@@ -441,7 +471,15 @@ public class Main {
     }
 
     /**
-     * Executes the build.
+     * Executes the build. If the constructor for this instance failed
+     * (e.g. returned after issuing a warning), this method returns
+     * immediately.
+     * 
+     * @param coreLoader The classloader to use to find core classes.
+     *                   May be <code>null</code>, in which case the
+     *                   system classloader is used.
+     * 
+     * @exception BuildException if the build fails
      */
     private void runBuild(ClassLoader coreLoader) throws BuildException {
 
@@ -552,6 +590,13 @@ public class Main {
         }
     }
 
+    /**
+     * Adds the listeners specified in the command line arguments,
+     * along with the default listener, to the specified project.
+     * 
+     * @param project The project to add listeners to.
+     *                Must not be <code>null</code>.
+     */
     protected void addBuildListeners(Project project) {
 
         // Add the default listener
@@ -570,6 +615,10 @@ public class Main {
         }
     }
 
+    // XXX: (Jon Skeet) Any reason for writing a message and then using a bare 
+    // RuntimeException rather than just using a BuildException here? Is it
+    // in case the message could end up being written to no loggers (as the loggers
+    // could have failed to be created due to this failure)?
     /**
      *  Creates the default build logger for sending build events to the ant log.
      */
@@ -603,7 +652,7 @@ public class Main {
     }
 
     /**
-     * Prints the usage of how to use this class to System.out
+     * Prints the usage information for this class to <code>System.out</code>.
      */
     private static void printUsage() {
         String lSep = System.getProperty("line.separator");
@@ -629,12 +678,30 @@ public class Main {
         System.out.println(msg.toString());
     }
 
+    /**
+     * Prints the Ant version information to <code>System.out</code>.
+     * 
+     * @exception BuildException if the version information is unavailable
+     */
     private static void printVersion() throws BuildException {
         System.out.println(getAntVersion());
     }
 
+    /**
+     * Cache of the Ant version information when it has been loaded.
+     */
     private static String antVersion = null;
 
+    /**
+     * Returns the Ant version information, if available. Once the information
+     * has been loaded once, it's cached and returned from the cache on future
+     * calls.
+     * 
+     * @return the Ant version information as a String 
+     *         (always non-<code>null</code>)
+     * 
+     * @exception BuildException if the version information is unavailable
+     */
     public static synchronized String getAntVersion() throws BuildException {
         if (antVersion == null) {
             try {
@@ -662,7 +729,11 @@ public class Main {
     }
 
      /**
-      * Print the project description, if any
+      * Prints the description of a project (if there is one) to 
+      * <code>System.out</code>.
+      * 
+      * @param project The project to display a description of.
+      *                Must not be <code>null</code>.
       */
     private static void printDescription(Project project) {
        if (project.getDescription() != null) {
@@ -671,7 +742,13 @@ public class Main {
     }
 
     /**
-     * Print out a list of all targets in the current buildfile
+     * Prints a list of all targets in the specified project to 
+     * <code>System.out</code>, optionally including subtargets.
+     * 
+     * @param project The project to display a description of.
+     *                Must not be <code>null</code>.
+     * @param printSubTargets Whether or not subtarget names should also be
+     *                        printed.
      */
     private static void printTargets(Project project, boolean printSubTargets) {
         // find the target with the longest name
@@ -717,7 +794,14 @@ public class Main {
     }
 
     /**
-     * Search for the insert position to keep names a sorted list of Strings
+     * Searches for the correct place to insert a name into a list so as
+     * to keep the list sorted alphabetically.
+     * 
+     * @param names The current list of names. Must not be <code>null</code>.
+     * @param name  The name to find a place for.
+     *              Must not be <code>null</code>.
+     * 
+     * @return the correct place in the list for the given name
      */
     private static int findTargetPosition(Vector names, String name) {
         int res = names.size();
@@ -730,7 +814,8 @@ public class Main {
     }
 
     /**
-     * Output a formatted list of target names with an optional description
+     * Writes a formatted list of target names to <code>System.out</code>
+     * with an optional description
      */
     private static void printTargets(Vector names, Vector descriptions, String heading, int maxlen) {
         // now, start printing the targets and their descriptions

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

@@ -1,7 +1,7 @@
 /*
  * The Apache Software License, Version 1.1
  *
- * Copyright (c) 2000-2001 The Apache Software Foundation.  All rights
+ * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -63,16 +63,44 @@ import org.apache.tools.ant.util.StringUtils;
  */
 public class NoBannerLogger extends DefaultLogger {
 
+    /** 
+     * Name of the current target, if it should
+     * be displayed on the next message. This is
+     * set when a target starts building, and reset
+     * to <code>null</code> after the first message for 
+     * the target is logged.
+     */
     protected String targetName;
 
+    /** Sole constructor. */
+    public NoBannerLogger() {
+    }
+
+    /**
+     * Notes the name of the target so it can be logged
+     * if it generates any messages.
+     * 
+     * @param event A BuildEvent containing target information.
+     *              Must not be <code>null</code>.
+     */
     public void targetStarted(BuildEvent event) {
         targetName = event.getTarget().getName();
     }
 
+    /** Resets the current target name to <code>null</code>. */
     public void targetFinished(BuildEvent event) {
         targetName = null;
     }
 
+    /**
+     * Logs a message for a target if it is of an appropriate
+     * priority, also logging the name of the target if this
+     * is the first message which needs to be logged for the
+     * target.
+     * 
+     * @param event A BuildEvent containing message information.
+     *              Must not be <code>null</code>.
+     */
     public void messageLogged(BuildEvent event) {
 
         if( event.getPriority() > msgOutputLevel ||

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

@@ -1,7 +1,7 @@
 /*
  * The Apache Software License, Version 1.1
  *
- * Copyright (c) 2000 The Apache Software Foundation.  All rights
+ * Copyright (c) 2000,2002 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -62,7 +62,7 @@ import java.io.File;
  * that path.
  *
  * The path can use path separators of either ':' or ';' and file separators
- * of either '/' or '\'
+ * of either '/' or '\'.
  *
  * @author Conor MacNeill (conor@ieee.org)
  *
@@ -74,21 +74,35 @@ public class PathTokenizer {
     private StringTokenizer tokenizer;
     
     /**
-     * A String which stores any path components which have been read ahead.
+     * A String which stores any path components which have been read ahead
+     * due to DOS filesystem compensation.
      */
     private String lookahead = null;
 
     /**
-     * Flag to indicate whether we are running on a platform with a DOS style
-     * filesystem
+     * Flag to indicate whether or not we are running on a platform with a
+     * DOS style filesystem
      */
     private boolean dosStyleFilesystem;
 
+    /**
+     * Constructs a path tokenizer for the specified path.
+     * 
+     * @param path The path to tokenize. Must not be <code>null</code>.
+     */
     public PathTokenizer(String path) {
        tokenizer = new StringTokenizer(path, ":;", false);
        dosStyleFilesystem = File.pathSeparatorChar == ';'; 
     }
 
+    /**
+     * Tests if there are more path elements available from this tokenizer's
+     * path. If this method returns <code>true</code>, then a subsequent call 
+     * to nextToken will successfully return a token.
+     * 
+     * @return <code>true</code> if and only if there is at least one token 
+     * in the string after the current position; <code>false</code> otherwise.
+     */
     public boolean hasMoreTokens() {
         if (lookahead != null) {
             return true;
@@ -97,6 +111,14 @@ public class PathTokenizer {
         return tokenizer.hasMoreTokens();
     }
     
+    /**
+     * Returns the next path element from this tokenizer.
+     * 
+     * @return the next path element from this tokenizer.
+     * 
+     * @exception NoSuchElementException if there are no more elements in this 
+     *            tokenizer's path.
+     */
     public String nextToken() throws NoSuchElementException {
         String token = null;
         if (lookahead != null) {