You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by bo...@apache.org on 2001/07/24 15:28:56 UTC
cvs commit: jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit BatchTest.java BriefJUnitResultFormatter.java FormatterElement.java JUnitTest.java JUnitTestRunner.java XMLConstants.java XMLJUnitResultFormatter.java XMLResultAggregator.java
bodewig 01/07/24 06:28:56
Modified: src/main/org/apache/tools/ant/taskdefs/optional/junit
BatchTest.java BriefJUnitResultFormatter.java
FormatterElement.java JUnitTest.java
JUnitTestRunner.java XMLConstants.java
XMLJUnitResultFormatter.java
XMLResultAggregator.java
Log:
Javadoc improvements.
Submitted by: robert burrell donkin <ro...@mac.com>
Revision Changes Path
1.6 +9 -5 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/BatchTest.java
Index: BatchTest.java
===================================================================
RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/BatchTest.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- BatchTest.java 2001/02/01 15:56:39 1.5
+++ BatchTest.java 2001/07/24 13:28:56 1.6
@@ -64,8 +64,13 @@
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>
* @author <a href="mailto:sbailliez@imediation.com">Stephane Bailliez</a>
@@ -99,10 +104,9 @@
}
/**
- * 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 @@
* 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 @@
}
/**
- * 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.
1.3 +4 -0 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/BriefJUnitResultFormatter.java
Index: BriefJUnitResultFormatter.java
===================================================================
RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/BriefJUnitResultFormatter.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- BriefJUnitResultFormatter.java 2001/05/05 14:02:50 1.2
+++ BriefJUnitResultFormatter.java 2001/07/24 13:28:56 1.3
@@ -61,7 +61,11 @@
/**
* 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 {
1.6 +57 -3 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/FormatterElement.java
Index: FormatterElement.java
===================================================================
RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/FormatterElement.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- FormatterElement.java 2001/05/23 16:58:03 1.5
+++ FormatterElement.java 2001/07/24 13:28:56 1.6
@@ -62,10 +62,26 @@
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><formatter></code> element in a <code><junit></code> task.
+ * <p> For example,
+ * <code><pre>
+ * <junit printsummary="no" haltonfailure="yes" fork="false">
+ * <formatter type="plain" usefile="false" />
+ * <test name="org.apache.ecs.InternationalCharTest" />
+ * </junit></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 @@
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 @@
}
}
+ /**
+ * <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 @@
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 @@
}
/**
- * 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() {
1.7 +18 -0 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTest.java
Index: JUnitTest.java
===================================================================
RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTest.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- JUnitTest.java 2001/07/11 09:29:50 1.6
+++ JUnitTest.java 2001/07/24 13:28:56 1.7
@@ -64,10 +64,17 @@
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 @@
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() {
1.12 +7 -4 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTestRunner.java
Index: JUnitTestRunner.java
===================================================================
RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTestRunner.java,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- JUnitTestRunner.java 2001/07/22 13:12:29 1.11
+++ JUnitTestRunner.java 2001/07/24 13:28:56 1.12
@@ -70,12 +70,15 @@
*
* <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>
1.4 +4 -2 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLConstants.java
Index: XMLConstants.java
===================================================================
RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLConstants.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- XMLConstants.java 2001/07/11 09:29:51 1.3
+++ XMLConstants.java 2001/07/24 13:28:56 1.4
@@ -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
1.11 +2 -0 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLJUnitResultFormatter.java
Index: XMLJUnitResultFormatter.java
===================================================================
RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLJUnitResultFormatter.java,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- XMLJUnitResultFormatter.java 2001/07/13 08:07:59 1.10
+++ XMLJUnitResultFormatter.java 2001/07/24 13:28:56 1.11
@@ -72,6 +72,8 @@
*
* @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 {
1.5 +12 -8 jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLResultAggregator.java
Index: XMLResultAggregator.java
===================================================================
RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLResultAggregator.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- XMLResultAggregator.java 2001/07/12 13:51:09 1.4
+++ XMLResultAggregator.java 2001/07/24 13:28:56 1.5
@@ -79,11 +79,11 @@
/**
- * 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 @@
/**
* 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 @@
/**
* 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 @@
}
/**
- * 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 @@
}
/**
+ * 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 @@
}
/**
- * 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 @@
}
/**
- * 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.