null.
- * @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 null, 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 null,
* 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 null.
* @param classpath the classpath to use to load the classes.
* May be null, in which case no path
* elements are set up to start with.
- * @param parentFirst if true indicates that the parent
- * classloader should be consulted before trying to load
- * the a class through this loader.
+ * @param parentFirst If true, 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 null.
- * @param classpath the classpath to use to load the classes. May be
+ * @param classpath The classpath to use to load the classes. May be
* null, in which case no path
* elements are set up to start with.
- *
- * @param parentFirst if true indicates that the parent
+ * @param parentFirst If true, 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 null,
* in which case the classloader which loaded this
* class is used as the parent.
- * @param parentFirst if true indicates that the parent
- * classloader should be consulted before trying to
+ * @param parentFirst If true, 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 null.
+ *
+ * @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
* null.
+ *
+ * @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 null.
+ * @param theClass The class to initialize.
+ * Must not be null.
*/
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 null.
+ * @param packageRoot The root of all packages to be included.
+ * Should not be null.
*/
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 null.
+ * @param packageRoot The root of all packages to be included.
+ * Should not be null.
*/
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 null.
+ * @param classname The name of the class to be loaded.
+ * Must not be null.
*
* @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
- * null.
+ * @param classname The name of the class to be loaded.
+ * Must not be null.
*
* @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 null.
*
* @return a stream to the required resource or null 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 null.
*
* @return a stream to the required resource or null 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
- * null.
+ * @param name The name of the system resource to load.
+ * Must not be null.
*
* @return a stream to the named resource, or null 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 null.
- * @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 null.
*
* @return a stream to the required resource or null 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
- * null.
+ * @param resourceName The name of the resource to check.
+ * Must not be null.
*
* @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 null.
*
* @return a URL for reading the resource, or null 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
- * null.
- * @return an enumeration of URLs for the resources.
+ * @param name The resource name to search for.
+ * Must not be null.
+ * @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 null.
- * @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 null.
*
* @return a stream to the required resource or null 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 null.
* @param resolve true 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 null.
*
* @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 null.
- * @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 null.
+ * @param classname The name of the class in the stream.
+ * Must not be null.
*
* @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
* null.
*
* @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
* null.
*
* @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
- * null.
+ * @param name The name of the class to be loaded.
+ * Must not be null.
*
* @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) {
diff --git a/src/main/org/apache/tools/ant/DemuxOutputStream.java b/src/main/org/apache/tools/ant/DemuxOutputStream.java
index cf9f471e0..ad6060835 100644
--- a/src/main/org/apache/tools/ant/DemuxOutputStream.java
+++ b/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 null.
+ * @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.
*/
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();
diff --git a/src/main/org/apache/tools/ant/IntrospectionHelper.java b/src/main/org/apache/tools/ant/IntrospectionHelper.java
index 6c634cdf4..aaba3cd02 100644
--- a/src/main/org/apache/tools/ant/IntrospectionHelper.java
+++ b/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 null.
+ *
+ * @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)
diff --git a/src/main/org/apache/tools/ant/Location.java b/src/main/org/apache/tools/ant/Location.java
index 0268a213f..1c350643c 100644
--- a/src/main/org/apache/tools/ant/Location.java
+++ b/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 null,
+ * 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 null,
+ * 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 "fileName: lineNumber: "
+ * if both file name and line number are known,
+ * "fileName: " if only the file name is known,
+ * and the empty string for unknown locations.
*/
public String toString() {
StringBuffer buf = new StringBuffer();
diff --git a/src/main/org/apache/tools/ant/Main.java b/src/main/org/apache/tools/ant/Main.java
index 06f7d5cb7..16c65effd 100644
--- a/src/main/org/apache/tools/ant/Main.java
+++ b/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
+ * null.
+ *
+ * @param t Throwable to print the message of.
+ * Must not be null.
*/
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 null.
+ * @param additionalUserProperties Any extra properties to use in this
+ * build. May be null, which is the equivalent to
+ * passing in an empty set of properties.
+ * @param coreLoader Classloader used for core classes. May be
+ * null 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 null.
*/
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 null.
+ *
+ * @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.
+ * + * Added to simulate File.getParentFile() from JDK 1.2. * - *
Added to simulate File.getParentFile() from JDK 1.2.
- *
- * @param file File
+ * @param file File to find parent of. Must not be null.
* @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.
+ *
+ * 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. * - *
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 null.
+ * @param suffix Suffix filename to look for in parents.
+ * Must not be null.
+ *
+ * @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 null, 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 null.
+ */
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 System.out.
*/
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 System.out.
+ *
+ * @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-null)
+ *
+ * @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
+ * System.out.
+ *
+ * @param project The project to display a description of.
+ * Must not be null.
*/
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
+ * System.out, optionally including subtargets.
+ *
+ * @param project The project to display a description of.
+ * Must not be null.
+ * @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 null.
+ * @param name The name to find a place for.
+ * Must not be null.
+ *
+ * @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 System.out
+ * with an optional description
*/
private static void printTargets(Vector names, Vector descriptions, String heading, int maxlen) {
// now, start printing the targets and their descriptions
diff --git a/src/main/org/apache/tools/ant/NoBannerLogger.java b/src/main/org/apache/tools/ant/NoBannerLogger.java
index ed0f0b7a2..0fa98ba49 100644
--- a/src/main/org/apache/tools/ant/NoBannerLogger.java
+++ b/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 null 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 null.
+ */
public void targetStarted(BuildEvent event) {
targetName = event.getTarget().getName();
}
+ /** Resets the current target name to null. */
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 null.
+ */
public void messageLogged(BuildEvent event) {
if( event.getPriority() > msgOutputLevel ||
diff --git a/src/main/org/apache/tools/ant/PathTokenizer.java b/src/main/org/apache/tools/ant/PathTokenizer.java
index d16c95e3a..c8addd958 100644
--- a/src/main/org/apache/tools/ant/PathTokenizer.java
+++ b/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 null.
+ */
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 true, then a subsequent call
+ * to nextToken will successfully return a token.
+ *
+ * @return true if and only if there is at least one token
+ * in the string after the current position; false 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) {