More JavaDoc documentation fixups.
Jon
Index: src/main/org/apache/tools/ant/BuildEvent.java
===================================================================
RCS file:
/home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/BuildEvent.java,v
retrieving revision 1.6
diff -u -r1.6 BuildEvent.java
--- src/main/org/apache/tools/ant/BuildEvent.java 10 Jan 2002 11:21:18
-0000 1.6
+++ src/main/org/apache/tools/ant/BuildEvent.java 15 Feb 2002 13:20:05
-0000
@@ -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,18 +55,42 @@
import java.util.EventObject;
+/**
+ * Class representing an event occurring during a build. An
+ * event is built by specifying either a project, a task or a target.
+ * A project level event will only have a project reference;
+ * a target level event will have project and target references;
+ * a task level event will have project, target and task references.
+ */
public class BuildEvent extends EventObject {
+
+ /** Project which emitted the event. */
private Project project;
+ /** Target which emitted the event, if specified. */
private Target target;
+ /** Task which emitted the event, if specified. */
private Task task;
+ /**
+ * Message associated with the event. This is only used for
+ * "messageLogged" events.
+ */
private String message;
+ /**
+ * The priority of the message, for "messageLogged" events.
+ */
private int priority = Project.MSG_VERBOSE;
+ /**
+ * The exception associated with this event, if any.
+ * This is only used for "taskFinished", "targetFinished",
+ * and "buildFinished" events.
+ */
private Throwable exception;
/**
- * Construct a BuildEvent for a project level event
+ * Construct a BuildEvent for a project level event.
*
* @param project the project that emitted the event.
+ * Should not be <code>null</code>.
*/
public BuildEvent(Project project) {
super(project);
@@ -76,9 +100,12 @@
}
/**
- * Construct a BuildEvent for a target level event
+ * Construct a BuildEvent for a target level event.
+ * The project associated with the event is derived
+ * from the given target.
*
* @param target the target that emitted the event.
+ * Must not be <code>null</code>.
*/
public BuildEvent(Target target) {
super(target);
@@ -88,9 +115,12 @@
}
/**
- * Construct a BuildEvent for a task level event
+ * Construct a BuildEvent for a task level event.
+ * The project and target associated with the event
+ * are derived from the given task.
*
* @param task the task that emitted the event.
+ * Must not be <code>null</code>.
*/
public BuildEvent(Task task) {
super(task);
@@ -99,24 +129,52 @@
this.task = task;
}
+ /**
+ * Sets the message and priority associated with this event.
+ * This is used for "messageLogged" events.
+ *
+ * @param message the message to be associated with this event.
+ * Should not be <code>null</code>.
+ * @param priority the priority to be associated with this event,
+ * as defined in the [EMAIL PROTECTED] Project Project}
class.
+ *
+ * @see BuildListener#messageLogged(BuildEvent)
+ */
public void setMessage(String message, int priority) {
this.message = message;
this.priority = priority;
}
+ /**
+ * Sets the exception associated with this event. This is used
+ * for "taskFinished", "targetFinished", and "buildFinished"
+ * events.
+ *
+ * @param exception The exception to be associated with this event.
+ * May be <code>null</code>.
+ *
+ * @see BuildListener#taskFinished(BuildEvent)
+ * @see BuildListener#targetFinished(BuildEvent)
+ * @see BuildListener#buildFinished(BuildEvent)
+ */
public void setException(Throwable exception) {
this.exception = exception;
}
/**
- * Returns the project that fired this event.
+ * Returns the project that fired this event.
+ *
+ * @return the project that fired this event
*/
public Project getProject() {
return project;
}
/**
- * Returns the target that fired this event.
+ * Returns the target that fired this event.
+ *
+ * @return the project that fired this event, or <code>null</code>
+ * if this event is a project level event.
*/
public Target getTarget() {
@@ -124,39 +182,52 @@
}
/**
- * Returns the task that fired this event.
+ * Returns the task that fired this event.
+ *
+ * @return the task that fired this event, or <code>null</code>
+ * if this event is a project or target level event.
*/
public Task getTask() {
return task;
}
/**
- * Returns the logging message. This field will only be set
- * for "messageLogged" events.
+ * Returns the logging message. This field will only be set
+ * for "messageLogged" events.
*
- * @see BuildListener#messageLogged(BuildEvent)
+ * @return the message associated with this event, or <code>null</code>
+ * if no message has been set.
+ *
+ * @see BuildListener#messageLogged(BuildEvent)
*/
public String getMessage() {
return message;
}
/**
- * Returns the priority of the logging message. This field will only
- * be set for "messageLogged" events.
+ * Returns the priority of the logging message. This field will only
+ * be set for "messageLogged" events. The meaning of this priority
+ * is as specified by the constants in the [EMAIL PROTECTED] Project
Project} class.
+ *
+ * @return the priority associated with this event.
*
- * @see BuildListener#messageLogged(BuildEvent)
+ * @see BuildListener#messageLogged(BuildEvent)
*/
public int getPriority(){
return priority;
}
/**
- * Returns the exception that was thrown, if any. This field will only
- * be set for "taskFinished", "targetFinished", and "buildFinished"
events.
- *
- * @see BuildListener#taskFinished(BuildEvent)
- * @see BuildListener#targetFinished(BuildEvent)
- * @see BuildListener#buildFinished(BuildEvent)
+ * Returns the exception that was thrown, if any. This field will only
+ * be set for "taskFinished", "targetFinished", and "buildFinished"
+ * events.
+ *
+ * @return the exception associated with this exception, or
+ * <code>null</code> if no exception has been set.
+ *
+ * @see BuildListener#taskFinished(BuildEvent)
+ * @see BuildListener#targetFinished(BuildEvent)
+ * @see BuildListener#buildFinished(BuildEvent)
*/
public Throwable getException() {
return exception;
Index: src/main/org/apache/tools/ant/BuildException.java
===================================================================
RCS file:
/home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/BuildException.java,v
retrieving revision 1.13
diff -u -r1.13 BuildException.java
--- src/main/org/apache/tools/ant/BuildException.java 10 Jan 2002 11:21:18
-0000 1.13
+++ src/main/org/apache/tools/ant/BuildException.java 15 Feb 2002 13:20:11
-0000
@@ -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
@@ -53,12 +53,11 @@
*/
package org.apache.tools.ant;
-
import java.io.PrintWriter;
import java.io.PrintStream;
/**
- * Signals an error condition during a build.
+ * Signals an error condition during a build
*
* @author James Duncan Davidson
*/
@@ -79,7 +78,9 @@
/**
* Constructs an exception with the given descriptive message.
- * @param msg Description of or information about the exception.
+ *
+ * @param msg A description of or information about the exception.
+ * Should not be <code>null</code>.
*/
public BuildException(String msg) {
super(msg);
@@ -88,8 +89,11 @@
/**
* Constructs an exception with the given message and exception as
* a root cause.
- * @param msg Description of or information about the exception.
- * @param cause Throwable that might have cause this one.
+ *
+ * @param msg A description of or information about the exception.
+ * Should not be <code>null</code> unless a cause is specified.
+ * @param cause The exception that might have caused this one.
+ * May be <code>null</code>.
*/
public BuildException(String msg, Throwable cause) {
super(msg);
@@ -99,9 +103,13 @@
/**
* Constructs an exception with the given message and exception as
* a root cause and a location in a file.
- * @param msg Description of or information about the exception.
- * @param cause Exception that might have cause this one.
- * @param location Location in the project file where the error occured.
+ *
+ * @param msg A description of or information about the exception.
+ * Should not be <code>null</code> unless a cause is specified.
+ * @param cause The exception that might have caused this one.
+ * May be <code>null</code>.
+ * @param location The location in the project file where the error
+ * occurred. Must not be <code>null</code>.
*/
public BuildException(String msg, Throwable cause, Location location) {
this(msg, cause);
@@ -110,7 +118,9 @@
/**
* Constructs an exception with the given exception as a root cause.
- * @param cause Exception that might have caused this one.
+ *
+ * @param cause The exception that might have caused this one.
+ * Should not be <code>null</code>.
*/
public BuildException(Throwable cause) {
super(cause.toString());
@@ -118,10 +128,13 @@
}
/**
- * Constructs an exception with the given descriptive message and a
location
- * in a file.
- * @param msg Description of or information about the exception.
- * @param location Location in the project file where the error occured.
+ * Constructs an exception with the given descriptive message and a
+ * location in a file.
+ *
+ * @param msg A description of or information about the exception.
+ * Should not be <code>null</code>.
+ * @param location The location in the project file where the error
+ * occurred. Must not be <code>null</code>.
*/
public BuildException(String msg, Location location) {
super(msg);
@@ -131,8 +144,11 @@
/**
* Constructs an exception with the given exception as
* a root cause and a location in a file.
- * @param cause Exception that might have cause this one.
- * @param location Location in the project file where the error occured.
+ *
+ * @param cause The exception that might have caused this one.
+ * Should not be <code>null</code>.
+ * @param location The location in the project file where the error
+ * occurred. Must not be <code>null</code>.
*/
public BuildException(Throwable cause, Location location) {
this(cause);
@@ -140,7 +156,10 @@
}
/**
- * Returns the nested exception.
+ * Returns the nested exception, if any.
+ *
+ * @return the nested exception, or <code>null</code> if no
+ * exception is associated with this one
*/
public Throwable getException() {
return cause;
@@ -148,30 +167,47 @@
/**
* Returns the location of the error and the error message.
+ *
+ * @return the location of the error and the error message
*/
public String toString() {
return location.toString() + getMessage();
}
/**
- * Sets the file location where the error occured.
+ * Sets the file location where the error occurred.
+ *
+ * @param location The file location where the error occurred.
+ * Must not be <code>null</code>.
*/
public void setLocation(Location location) {
this.location = location;
}
/**
- * Returns the file location where the error occured.
+ * Returns the file location where the error occurred.
+ *
+ * @return the file location where the error occurred.
*/
public Location getLocation() {
return location;
}
- // Override stack trace methods to show original cause:
+ /**
+ * Prints the stack trace for this exception and any
+ * nested exception to <code>System.err</code>.
+ */
public void printStackTrace() {
printStackTrace(System.err);
}
+ /**
+ * Prints the stack trace of this exception and any nested
+ * exception to the specified PrintStream.
+ *
+ * @param ps The PrintStream to print the stack trace to.
+ * Must not be <code>null</code>.
+ */
public void printStackTrace(PrintStream ps) {
synchronized (ps) {
super.printStackTrace(ps);
@@ -182,6 +218,13 @@
}
}
+ /**
+ * Prints the stack trace of this exception and any nested
+ * exception to the specified PrintWriter.
+ *
+ * @param pw The PrintWriter to print the stack trace to.
+ * Must not be <code>null</code>.
+ */
public void printStackTrace(PrintWriter pw) {
synchronized (pw) {
super.printStackTrace(pw);
Index: src/main/org/apache/tools/ant/BuildListener.java
===================================================================
RCS file:
/home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/BuildListener.java,v
retrieving revision 1.5
diff -u -r1.5 BuildListener.java
--- src/main/org/apache/tools/ant/BuildListener.java 10 Jan 2002 11:21:18
-0000 1.5
+++ src/main/org/apache/tools/ant/BuildListener.java 15 Feb 2002 13:20:17
-0000
@@ -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
@@ -57,62 +57,84 @@
import java.util.EventListener;
/**
- * Classes that implement this interface will be notified when
- * things happend during a build.
+ * Instances of classes that implement this interface can register
+ * to be notified when things happened during a build.
*
- * @see BuildEvent
- * @see Project#addBuildListener(BuildListener)
+ * @see BuildEvent
+ * @see Project#addBuildListener(BuildListener)
*/
public interface BuildListener extends EventListener {
/**
- * Fired before any targets are started.
+ * Signals that a build has started. This event
+ * is fired before any targets have started.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be <code>null</code>.
*/
void buildStarted(BuildEvent event);
/**
- * Fired after the last target has finished. This event
- * will still be thrown if an error occured during the build.
+ * Signals that the last target has finished. This event
+ * will still be fired if an error occurred during the build.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be <code>null</code>.
*
- * @see BuildEvent#getException()
+ * @see BuildEvent#getException()
*/
void buildFinished(BuildEvent event);
/**
- * Fired when a target is started.
+ * Signals that a target is starting.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be <code>null</code>.
*
- * @see BuildEvent#getTarget()
+ * @see BuildEvent#getTarget()
*/
void targetStarted(BuildEvent event);
/**
- * Fired when a target has finished. This event will
- * still be thrown if an error occured during the build.
+ * Signals that a target has finished. This event will
+ * still be fired if an error occurred during the build.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be <code>null</code>.
*
- * @see BuildEvent#getException()
+ * @see BuildEvent#getException()
*/
void targetFinished(BuildEvent event);
/**
- * Fired when a task is started.
+ * Signals that a task is starting.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be <code>null</code>.
*
- * @see BuildEvent#getTask()
+ * @see BuildEvent#getTask()
*/
void taskStarted(BuildEvent event);
/**
- * Fired when a task has finished. This event will still
- * be throw if an error occured during the build.
+ * Signals that a task has finished. This event will still
+ * be fired if an error occurred during the build.
*
- * @see BuildEvent#getException()
+ * @param event An event with any relevant extra information.
+ * Must not be <code>null</code>.
+ *
+ * @see BuildEvent#getException()
*/
void taskFinished(BuildEvent event);
/**
- * Fired whenever a message is logged.
+ * Signals a message logging event.
+ *
+ * @param event An event with any relevant extra information.
+ * Must not be <code>null</code>.
*
- * @see BuildEvent#getMessage()
- * @see BuildEvent#getPriority()
+ * @see BuildEvent#getMessage()
+ * @see BuildEvent#getPriority()
*/
void messageLogged(BuildEvent event);
}
Index: src/main/org/apache/tools/ant/BuildLogger.java
===================================================================
RCS file:
/home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/BuildLogger.java,v
retrieving revision 1.7
diff -u -r1.7 BuildLogger.java
--- src/main/org/apache/tools/ant/BuildLogger.java 10 Jan 2002 11:21:19
-0000 1.7
+++ src/main/org/apache/tools/ant/BuildLogger.java 15 Feb 2002 13:20:21
-0000
@@ -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
@@ -59,45 +59,51 @@
/**
* Interface used by Ant to log the build output.
*
- * A build logger is a build listener which has the 'right' to send output to
the
- * ant log, which is usually System.out unles redirected by the -logfile
option.
+ * A build logger is a build listener which has the 'right' to send output to
+ * the ant log, which is usually <code>System.out</code> unless redirected by
+ * the <code>-logfile</code> option.
*
* @author Conor MacNeill
*/
public interface BuildLogger extends BuildListener {
+
/**
- * Set the msgOutputLevel this logger is to respond to.
+ * Sets the msgOutputLevel this logger is to respond to.
*
- * Only messages with a message level lower than or equal to the given
level are
- * output to the log.
+ * Only messages with a message level lower than or equal to the given
+ * level are output to the log.
* <P>
- * Constants for the message levels are in Project.java. The order of
- * the levels, from least to most verbose, is MSG_ERR, MSG_WARN,
- * MSG_INFO, MSG_VERBOSE, MSG_DEBUG.
+ * Constants for the message levels are in the
+ * [EMAIL PROTECTED] Project Project} class. The order of the levels, from
least
+ * to most verbose, is <code>MSG_ERR</code>, <code>MSG_WARN</code>,
+ * <code>MSG_INFO</code>, <code>MSG_VERBOSE</code>,
+ * <code>MSG_DEBUG</code>.
*
* @param level the logging level for the logger.
*/
void setMessageOutputLevel(int level);
/**
- * Set the output stream to which this logger is to send its output.
+ * Sets the output stream to which this logger is to send its output.
*
- * @param output the output stream for the logger.
+ * @param output The output stream for the logger.
+ * Must not be <code>null</code>.
*/
void setOutputPrintStream(PrintStream output);
/**
- * Set this logger to produce emacs (and other editor) friendly output.
+ * Sets this logger to produce emacs (and other editor) friendly output.
*
- * @param emacsMode true if output is to be unadorned so that emacs and
other
- * editors can parse files names, etc.
+ * @param emacsMode <code>true</code> if output is to be unadorned so that
+ * emacs and other editors can parse files names, etc.
*/
void setEmacsMode(boolean emacsMode);
/**
- * Set the output stream to which this logger is to send error messages.
+ * Sets the output stream to which this logger is to send error messages.
*
- * @param err the error stream for the logger.
+ * @param err The error stream for the logger.
+ * Must not be <code>null<code>.
*/
void setErrorPrintStream(PrintStream err);
}
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
