Fixed up JavaDoc comments again.

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

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

@@ -971,7 +971,7 @@ public class AntClassLoader extends ClassLoader implements BuildListener {
      * reading the class from the stream.
      */
     private Class getClassFromStream(InputStream stream, String classname)
-                throws IOException {
+                throws IOException, SecurityException {
         ByteArrayOutputStream baos = new ByteArrayOutputStream();
         int bytesRead = -1;
         byte[] buffer = new byte[BUFFER_SIZE];

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

@@ -758,7 +758,7 @@ strLoop:
      *            incorrectly (i.e. if it is <code>null</code>, doesn't exist,
      *            or isn't a directory).
      */
-    public void scan() {
+    public void scan() throws IllegalStateException {
         if (basedir == null) {
             throw new IllegalStateException("No basedir set");
         }

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

@@ -430,7 +430,8 @@ public class IntrospectionHelper implements BuildListener {
      *                           method is available to handle it, or if
      *                           the handling method fails.
      */
-    public void addText(Project project, Object element, String text) {
+    public void addText(Project project, Object element, String text) 
+        throws BuildException {
         if (addText == null) {
             // Element doesn't handle text content
             if ( text.trim().length() == 0 ) {
@@ -845,6 +846,8 @@ public class IntrospectionHelper implements BuildListener {
     /**
      * Clears all storage used by this class, including the static cache of 
      * helpers.
+     * 
+     * @param event Ignored in this implementation.
      */
     public void buildFinished(BuildEvent event) {
         attributeTypes.clear();

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

@@ -87,7 +87,11 @@ public class NoBannerLogger extends DefaultLogger {
         targetName = event.getTarget().getName();
     }
 
-    /** Resets the current target name to <code>null</code>. */
+    /** 
+     * Resets the current target name to <code>null</code>.
+     * 
+     * @param event Ignored in this implementation.
+     */
     public void targetFinished(BuildEvent event) {
         targetName = null;
     }

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

@@ -140,11 +140,19 @@ public class ProjectHelper {
     }
 
     
-    /** Discover a project helper instance. Uses the same patterns
-     *  as JAXP, commons-logging, etc: a system property, a JDK1.3
-     *  service discovery, default.
+    /** 
+     * Discovers a project helper instance. Uses the same patterns
+     * as JAXP, commons-logging, etc: a system property, a JDK1.3
+     * service discovery, default.
+     * 
+     * @return a ProjectHelper, either a custom implementation
+     * if one is available and configured, or the default implementation
+     * otherwise.
+     * 
+     * @exception BuildException if a specified helper class cannot
+     * be loaded/instantiated.
      */
-    public static ProjectHelper getProjectHelper()
+    public static ProjectHelper getProjectHelper() 
         throws BuildException {
         // Identify the class loader we will be using. Ant may be
         // in a webapp or embeded in a different app
@@ -206,9 +214,18 @@ public class ProjectHelper {
         }
     }
 
-    /** Create a new helper. It'll first try the thread class loader,
-     *  then Class.forName() will load from the same loader that
-     *  loaded this class.
+    /** 
+     * Creates a new helper instance from the name of the class. 
+     * It'll first try the thread class loader, then Class.forName() 
+     * will load from the same loader that loaded this class.
+     * 
+     * @param helperClass The name of the class to create an instance
+     *                    of. Must not be <code>null</code>.
+     * 
+     * @return a new instance of the specified class.
+     * 
+     * @exception BuildException if the class cannot be found or
+     * cannot be appropriate instantiated.
      */
     private static ProjectHelper newHelper(String helperClass)
         throws BuildException {
@@ -232,11 +249,13 @@ public class ProjectHelper {
     }
 
     /**
-     *  JDK1.1 compatible access to the context class loader.
-     *  Cut&paste from Jaxp.
+     * JDK1.1 compatible access to the context class loader.
+     * Cut&paste from JAXP.
+     * 
+     * @return the current context class loader, or <code>null</code>
+     * if the context class loader is unavailable.
      */
-    public static ClassLoader getContextClassLoader()
-        throws BuildException {
+    public static ClassLoader getContextClassLoader() {
         if (!LoaderUtils.isContextLoaderAvailable()) {
             return null;
         }
@@ -357,6 +376,9 @@ public class ProjectHelper {
      * Replaces <code>${xxx}</code> style constructions in the given value with 
      * the string value of the corresponding properties.
      *
+     * @param project The project containing the properties to replace.
+     *                Must not be <code>null</code>.
+     * 
      * @param value The string to be scanned for property references.
      *              May be <code>null</code>.
      *

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

@@ -108,6 +108,9 @@ public class TaskAdapter extends Task {
     
     /**
      * Executes the proxied task.
+     * 
+     * @exception BuildException if the project could not be set
+     * or the method could not be executed.
      */
     public void execute() throws BuildException {
         Method setProjectM = null;

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

@@ -187,6 +187,11 @@ public class UnknownElement extends Task {
      *
      * @param parent The configured object for the parent. 
      *               Must not be <code>null</code>.
+     * 
+     * @param parentWrapper The wrapper containing child wrappers
+     *                      to be configured. Must not be <code>null</code>
+     *                      if there are any children.
+     * 
      * @exception BuildException if the children cannot be configured.
      */
     protected void handleChildren(Object parent,
@@ -286,6 +291,8 @@ public class UnknownElement extends Task {
      *             <code>"task"</code>. Should not be <code>null</code>.
      * @param elementName The name of the element which could not be found.
      *                    Should not be <code>null</code>.
+     * 
+     * @return a detailed description of what might have caused the problem.
      */
     protected BuildException getNotFoundException(String what,
                                                   String elementName) {

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

@@ -92,6 +92,8 @@ public class XmlLogger implements BuildListener {
     /** 
      * Returns a default DocumentBuilder instance or throws an
      * ExceptionInInitializerError if it can't be created.
+     * 
+     * @return a default DocumentBuilder instance.
      */
     private static DocumentBuilder getDocumentBuilder() {
         try {
@@ -141,7 +143,12 @@ public class XmlLogger implements BuildListener {
 
     /** Utility class representing the time an element started. */
     private static class TimedElement {
+        /** 
+         * Start time in milliseconds 
+         * (as returned by <code>System.currentTimeMillis()</code>). 
+         */
         long startTime;
+        /** Element created at the start time. */ 
         Element element;
     }