More JavaDoc documentation fixups.

Submitted by:	Jon Skeet <jon.skeet@peramon.com>


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

src/main/org/apache/tools/ant/BuildEvent.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,18 +55,42 @@ package org.apache.tools.ant;
 
 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 @@ public class BuildEvent extends EventObject {
     }
     
     /**
-     * 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 @@ public class BuildEvent extends EventObject {
     }
     
     /**
-     * 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 @@ public class BuildEvent extends EventObject {
         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 {@link 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 @@ public class BuildEvent extends EventObject {
     }
 
     /**
-     *  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 {@link 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.
+     * 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)
+     * @see BuildListener#taskFinished(BuildEvent)
+     * @see BuildListener#targetFinished(BuildEvent)
+     * @see BuildListener#buildFinished(BuildEvent)
      */
     public Throwable getException() {
         return exception;

src/main/org/apache/tools/ant/BuildException.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
@@ -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 @@ public class BuildException extends RuntimeException {
 
     /**
      * 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 @@ public class BuildException extends RuntimeException {
     /**
      * 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 @@ public class BuildException extends RuntimeException {
     /**
      * 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 @@ public class BuildException extends RuntimeException {
 
     /**
      * 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 @@ public class BuildException extends RuntimeException {
     }
 
     /**
-     * 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 @@ public class BuildException extends RuntimeException {
     /**
      * 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 @@ public class BuildException extends RuntimeException {
     }
 
     /**
-     * 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 @@ public class BuildException extends RuntimeException {
 
     /**
      * 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 @@ public class BuildException extends RuntimeException {
         }
     }
     
+    /**
+     * 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);

src/main/org/apache/tools/ant/BuildListener.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
@@ -57,62 +57,84 @@ package org.apache.tools.ant;
 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);
 }

src/main/org/apache/tools/ant/BuildLogger.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
@@ -59,45 +59,51 @@ import java.io.PrintStream;
 /**
  * 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 
+     * {@link 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);    
 }