Javadoc improvements.

Submitted by:	robert burrell donkin <robertdonkin@mac.com>


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

src/main/org/apache/tools/ant/taskdefs/optional/junit/BatchTest.java

@@ -64,7 +64,12 @@ import java.util.*;
 import java.io.File;
 
 /**
- * Create JUnitTests from a list of files.
+ * <p> Create then run <code>JUnitTest</code>'s based on the list of files given by the fileset attribute.
+ *
+ * <p> Every <code>.java</code> or <code>.class</code> file in the fileset is 
+ * assumed to be a testcase. 
+ * A <code>JUnitTest</code> is created for each of these named classes with basic setup
+ * inherited from the parent <code>BatchTest</code>.
  *
  * @author <a href="mailto:jeff.martin@synamic.co.uk">Jeff Martin</a>
  * @author <a href="mailto:stefan.bodewig@epost.de">Stefan Bodewig</a>
@@ -99,10 +104,9 @@ public final class BatchTest extends BaseTest {
     }
 
     /**
-     * return all <tt>JUnitTest</tt> instances obtain by applying the fileset rules.
+     * Return all <tt>JUnitTest</tt> instances obtain by applying the fileset rules.
      * @return  an enumeration of all elements of this batchtest that are
      * a <tt>JUnitTest</tt> instance.
-     * @see addTestsTo(Vector)
      */
     public final Enumeration elements(){
         JUnitTest[] tests = createAllJUnitTest();
@@ -142,7 +146,7 @@ public final class BatchTest extends BaseTest {
      * Iterate over all filesets and return the filename of all files
      * that end with <tt>.java</tt> or <tt>.class</tt>. This is to avoid
      * wrapping a <tt>JUnitTest</tt> over an xml file for example. A Testcase
-     * is obviouslly a java file (compiled or not).
+     * is obviously a java file (compiled or not).
      * @return an array of filenames without their extension. As they should
      * normally be taken from their root, filenames should match their fully
      * qualified class name (If it is not the case it will fail when running the test).
@@ -172,7 +176,7 @@ public final class BatchTest extends BaseTest {
     }
 
     /**
-     * convenient method to convert a pathname without extension to a
+     * Convenient method to convert a pathname without extension to a
      * fully qualified classname. For example <tt>org/apache/Whatever</tt> will
      * be converted to <tt>org.apache.Whatever</tt>
      * @param filename the filename to "convert" to a classname.

src/main/org/apache/tools/ant/taskdefs/optional/junit/BriefJUnitResultFormatter.java

@@ -61,7 +61,11 @@ import junit.framework.*;
 /**
  * Prints plain text output of the test to a specified Writer.
  * Inspired by the PlainJUnitResultFormatter.
+ *
  * @author <a href="mailto:robertdw@bigpond.net.au">Robert Watkins</a>
+ *
+ * @see FormatterElement
+ * @see PlainJUnitResultFormatter
  */
 public class BriefJUnitResultFormatter implements JUnitResultFormatter {
         

src/main/org/apache/tools/ant/taskdefs/optional/junit/FormatterElement.java

@@ -62,10 +62,26 @@ import java.io.FileOutputStream;
 import java.io.OutputStream;
 
 /**
- * Serves as a wrapper the implementations of JUnitResultFormatter,
- * for example as a nested <formatter> element in <junit>.
+ * <p> A wrapper for the implementations of <code>JUnitResultFormatter</code>.
+ * In particular, used as a nested <code>&lt;formatter&gt;</code> element in a <code>&lt;junit&gt;</code> task.
+ * <p> For example, 
+ * <code><pre>
+ *       &lt;junit printsummary="no" haltonfailure="yes" fork="false"&gt;
+ *           &lt;formatter type="plain" usefile="false" /&gt;
+ *           &lt;test name="org.apache.ecs.InternationalCharTest" /&gt;
+ *       &lt;/junit&gt;</pre></code>
+ * adds a <code>plain</code> type implementation (<code>PlainJUnitResultFormatter</code>) to display the results of the test.
+ *
+ * <p> Either the <code>type</code> or the <code>classname</code> attribute
+ * must be set. 
  *
  * @author <a href="mailto:stefan.bodewig@epost.de">Stefan Bodewig</a>
+ *
+ * @see JUnitTask
+ * @see XMLJUnitResultFormatter
+ * @see BriefJUnitResultFormatter
+ * @see PlainJUnitResultFormatter
+ * @see JUnitResultFormatter
  */
 public class FormatterElement {
 
@@ -75,6 +91,18 @@ public class FormatterElement {
     private File outFile;
     private boolean useFile = true;
 
+    /**
+     * <p> Quick way to use a standard formatter.
+     *
+     * <p> At the moment, there are three supported standard formatters.
+     * <ul>
+     * <li> The <code>xml</code> type uses a <code>XMLJUnitResultFormatter</code>.
+     * <li> The <code>brief</code> type uses a <code>BriefJUnitResultFormatter</code>.
+     * <li> The <code>plain</code> type (the default) uses a <code>PlainJUnitResultFormatter</code>.
+     * </ul>
+     *
+     * <p> Sets <code>classname</code> attribute - so you can't use that attribute if you use this one.
+     */
     public void setType(TypeAttribute type) {
         if ("xml".equals(type.getValue())) {
             setClassname("org.apache.tools.ant.taskdefs.optional.junit.XMLJUnitResultFormatter");
@@ -89,10 +117,18 @@ public class FormatterElement {
         }
     }
 
+    /**
+     * <p> Set name of class to be used as the formatter.
+     *
+     * <p> This class must implement <code>JUnitResultFormatter</code>
+     */
     public void setClassname(String classname) {
         this.classname = classname;
     }
 
+    /**
+     * Get name of class to be used as the formatter.
+     */
     public String getClassname() {
         return classname;
     }
@@ -105,18 +141,34 @@ public class FormatterElement {
         return extension;
     }
 
+    /**
+     * <p> Set the file which the formatte should log to.
+     *
+     * <p> Note that logging to file must be enabled .
+     */
     void setOutfile(File out) {
         this.outFile = out;
     }
 
+    /**
+     * <p> Set output stream for formatter to use.
+     *
+     * <p> Defaults to standard out.
+     */
     public void setOutput(OutputStream out) {
         this.out = out;
     }
 
+    /**
+     * Set whether the formatter should log to file.
+     */
     public void setUseFile(boolean useFile) {
         this.useFile = useFile;
     }
 
+    /**
+     * Get whether the formatter should log to file.
+     */
     boolean getUseFile() {
         return useFile;
     }
@@ -160,7 +212,9 @@ public class FormatterElement {
     }
 
     /**
-     * Enumerated attribute with the values "plain" and "xml".
+     * <p> Enumerated attribute with the values "plain", "xml" and "brief".
+     * 
+     * <p> Use to enumerate options for <code>type</code> attribute.
      */
     public static class TypeAttribute extends EnumeratedAttribute {
         public String[] getValues() {

src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTest.java

@@ -64,10 +64,17 @@ import java.util.Properties;
 import java.util.Vector;
 
 /**
+ * <p> Run a single JUnit test.
+ *
+ * <p> The JUnit test is actually run by {@link JUnitTestRunner}.
+ * So read the doc comments for that class :)
  *
  * @author Thomas Haas
  * @author <a href="mailto:stefan.bodewig@epost.de">Stefan Bodewig</a>,
  * @author <a href="mailto:sbailliez@imediation.com">Stephane Bailliez</a>
+ *
+ * @see JUnitTask
+ * @see JUnitTestRunner
  */
 public class JUnitTest extends BaseTest {
     
@@ -99,19 +106,30 @@ public class JUnitTest extends BaseTest {
         this.haltOnFail = haltOnFail;
     }
 
+    /** 
+     * Set the name of the test class.
+     */
     public void setName(String value) {
         name = value;
     }
 
+    /**
+     * Set the name of the output file.
+     */
     public void setOutfile(String value) {
         outfile = value;
     }
 
+    /** 
+     * Get the name of the test class.
+     */
     public String getName() {
         return name;
     }
 
     /**
+     * Get the name of the output file
+     * 
      * @return the name of the output file.
      */
     public String getOutfile() {

src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTestRunner.java

@@ -70,12 +70,15 @@ import java.util.Vector;
  *
  * <p>This TestRunner expects a name of a TestCase class as its
  * argument. If this class provides a static suite() method it will be
- * called and the resulting Test will be run.
+ * called and the resulting Test will be run. So, the signature should be 
+ * <pre><code>
+ *     public static junit.framework.Test suite()
+ * </code></pre>
  *
- * <p>Otherwise all public methods starting with "test" and taking no
- * argument will be run.
+ * <p> If no such method exists, all public methods starting with "test" and taking no
+ * argument will be run. 
  *
- * <p>Summary output is generated at the end.
+ * <p> Summary output is generated at the end. 
  *
  * @author <a href="mailto:stefan.bodewig@epost.de">Stefan Bodewig</a>
  * @author <a href="mailto:erik@hatcher.net">Erik Hatcher</a>

src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLConstants.java

@@ -54,12 +54,14 @@
 package org.apache.tools.ant.taskdefs.optional.junit;
 
 /**
- * Interface that groups all constants used throughout the <tt>XML<tt>
+ * <p> Interface groups XML constants.
+ * Interface that groups all constants used throughout the <tt>XML</tt>
  * documents that are generated by the <tt>XMLJUnitResultFormatter</tt>
  * As of now the DTD is:
- *
+ * <code><pre>
  * <----------------- @todo describe DTDs ---------------------->
  *
+ * </pre></code>
  * @author <a href="mailto:sbailliez@imediation.com">Stephane Bailliez</a>
  * @see XMLJUnitResultFormatter
  * @see XMLResultAggregator

src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLJUnitResultFormatter.java

@@ -72,6 +72,8 @@ import junit.framework.TestCase;
  *
  * @author <a href="mailto:stefan.bodewig@epost.de">Stefan Bodewig</a>
  * @author <a href="mailto:erik@hatcher.net">Erik Hatcher</a>
+ *
+ * @see FormatterElement 
  */
 
 public class XMLJUnitResultFormatter implements JUnitResultFormatter, XMLConstants {

src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLResultAggregator.java

@@ -79,11 +79,11 @@ import org.apache.tools.ant.util.DOMElementWriter;
 
 
 /**
- * This is an helper class that will aggregate all testsuites under a specific
+ * <p> This is an helper class that will aggregate all testsuites under a specific
  * directory and create a new single document. It is not particulary clean but
  * should be helpful while I am thinking about another technique.
  *
- * The main problem is due to the fact that a JVM can be forked for a testcase
+ * <p> The main problem is due to the fact that a JVM can be forked for a testcase
  * thus making it impossible to aggregate all testcases since the listener is
  * (obviously) in the forked JVM. A solution could be to write a
  * TestListener that will receive events from the TestRunner via sockets. This
@@ -119,7 +119,7 @@ public class XMLResultAggregator extends Task implements XMLConstants {
     
     /**
      * Set the name of the file aggregating the results. It must be relative
-     * from the <tt>todir</tt> attribute. If not set it will use {@link DEFAULT_FILENAME}
+     * from the <tt>todir</tt> attribute. If not set it will use {@link #DEFAULT_FILENAME}
      * @param  value   the name of the file.
      * @see #setTodir(File)
      */
@@ -129,7 +129,7 @@ public class XMLResultAggregator extends Task implements XMLConstants {
     
     /**
      * Set the destination directory where the results should be written. If not
-     * set if will use {@link DEFAULT_DIR}. When given a relative directory
+     * set if will use {@link #DEFAULT_DIR}. When given a relative directory
      * it will resolve it from the project directory.
      * @param value    the directory where to write the results, absolute or
      * relative.
@@ -172,7 +172,7 @@ public class XMLResultAggregator extends Task implements XMLConstants {
     }
     
     /**
-     * get the full destination file where to write the result. It is made of
+     * Get the full destination file where to write the result. It is made of
      * the <tt>todir</tt> and <tt>tofile</tt> attributes.
      * @return the destination file where should be written the result file.
      */
@@ -187,6 +187,8 @@ public class XMLResultAggregator extends Task implements XMLConstants {
     }
     
     /**
+     * Get all <code>.xml</code> files in the fileset.
+     *
      * @return all files in the fileset that end with a '.xml'.
      */
     protected File[] getFiles() {
@@ -234,7 +236,8 @@ public class XMLResultAggregator extends Task implements XMLConstants {
     }
     
     /**
-     * Create a DOM tree with firstchild as 'testsuites' and aggregates all
+     * <p> Create a DOM tree. 
+     * Has 'testsuites' as firstchild and aggregates all
      * testsuite results that exists in the base directory.
      * @return	the root element of DOM tree that aggregates all testsuites.
      */
@@ -277,9 +280,10 @@ public class XMLResultAggregator extends Task implements XMLConstants {
     }
     
     /**
-     * Add a new testsuite node to the document, the main difference is that it
+     * <p> Add a new testsuite node to the document.
+     * The main difference is that it
      * split the previous fully qualified name into a package and a name.
-     * For example: <tt>org.apache.Whatever</tt> will be splitted in
+     * <p> For example: <tt>org.apache.Whatever</tt> will be split into
      * <tt>org.apache</tt> and <tt>Whatever</tt>.
      * @param root the root element to which the <tt>testsuite</tt> node should
      *        be appended.