Merge pull request junit-team#648 from dlam/master

Fix inconsistencies in javadocs.

Author: David Saff

src/main/java/junit/framework/TestSuite.java

@@ -14,33 +14,30 @@
 import org.junit.internal.MethodSorter;
 
 /**
- * <p>A <code>TestSuite</code> is a <code>Composite</code> of Tests.
+ * A <code>TestSuite</code> is a <code>Composite</code> of Tests.
  * It runs a collection of test cases. Here is an example using
  * the dynamic test definition.
  * <pre>
  * TestSuite suite= new TestSuite();
  * suite.addTest(new MathTest("testAdd"));
  * suite.addTest(new MathTest("testDivideByZero"));
  * </pre>
- * </p>
- *
- * <p>Alternatively, a TestSuite can extract the tests to be run automatically.
+ * <p>
+ * Alternatively, a TestSuite can extract the tests to be run automatically.
  * To do so you pass the class of your TestCase class to the
  * TestSuite constructor.
  * <pre>
  * TestSuite suite= new TestSuite(MathTest.class);
  * </pre>
- * </p>
- *
- * <p>This constructor creates a suite with all the methods
- * starting with "test" that take no arguments.</p>
- *
- * <p>A final option is to do the same for a large array of test classes.
+ * <p>
+ * This constructor creates a suite with all the methods
+ * starting with "test" that take no arguments.
+ * <p>
+ * A final option is to do the same for a large array of test classes.
  * <pre>
  * Class[] testClasses = { MathTest.class, AnotherTest.class }
  * TestSuite suite= new TestSuite(testClasses);
  * </pre>
- * </p>
  *
  * @see Test
  */

src/main/java/junit/textui/TestRunner.java

@@ -15,17 +15,17 @@
  * <pre>
  * java junit.textui.TestRunner [-wait] TestCaseClass
  * </pre>
- *
- * <p>TestRunner expects the name of a TestCase class as argument.
+ * <p>
+ * TestRunner expects the name of a TestCase class as argument.
  * If this class defines a static <code>suite</code> method it
  * will be invoked and the returned test is run. Otherwise all
- * the methods starting with "test" having no arguments are run.</p>
- *
- * <p> When the wait command line argument is given TestRunner
- * waits until the users types RETURN.</p>
- *
- * <p>TestRunner prints a trace as the tests are executed followed by a
- * summary at the end.</p>
+ * the methods starting with "test" having no arguments are run.
+ * <p>
+ * When the wait command line argument is given TestRunner
+ * waits until the users types RETURN.
+ * <p>
+ * TestRunner prints a trace as the tests are executed followed by a
+ * summary at the end.
  */
 public class TestRunner extends BaseTestRunner {
     private ResultPrinter fPrinter;

src/main/java/org/junit/After.java

@@ -6,13 +6,13 @@
 import java.lang.annotation.Target;
 
 /**
- * <p>If you allocate external resources in a {@link org.junit.Before} method you need to release them
+ * If you allocate external resources in a {@link org.junit.Before} method you need to release them
  * after the test runs. Annotating a <code>public void</code> method
  * with <code>&#064;After</code> causes that method to be run after the {@link org.junit.Test} method. All <code>&#064;After</code>
  * methods are guaranteed to run even if a {@link org.junit.Before} or {@link org.junit.Test} method throws an
  * exception. The <code>&#064;After</code> methods declared in superclasses will be run after those of the current
- * class, unless they are overridden in the current class.</p>
- *
+ * class, unless they are overridden in the current class.
+ * <p>
  * Here is a simple example:
  * <pre>
  * public class Example {

src/main/java/org/junit/AfterClass.java

@@ -6,13 +6,13 @@
 import java.lang.annotation.Target;
 
 /**
- * <p>If you allocate expensive external resources in a {@link org.junit.BeforeClass} method you need to release them
+ * If you allocate expensive external resources in a {@link org.junit.BeforeClass} method you need to release them
  * after all the tests in the class have run. Annotating a <code>public static void</code> method
  * with <code>&#064;AfterClass</code> causes that method to be run after all the tests in the class have been run. All <code>&#064;AfterClass</code>
  * methods are guaranteed to run even if a {@link org.junit.BeforeClass} method throws an
  * exception. The <code>&#064;AfterClass</code> methods declared in superclasses will be run after those of the current
- * class, unless they are shadowed in the current class.</p>
- *
+ * class, unless they are shadowed in the current class.
+ * <p>
  * Here is a simple example:
  * <pre>
  * public class Example {

src/main/java/org/junit/Before.java

@@ -6,13 +6,12 @@
 import java.lang.annotation.Target;
 
 /**
- * <p>When writing tests, it is common to find that several tests need similar
+ * When writing tests, it is common to find that several tests need similar
  * objects created before they can run. Annotating a <code>public void</code> method
  * with <code>&#064;Before</code> causes that method to be run before the {@link org.junit.Test} method.
  * The <code>&#064;Before</code> methods of superclasses will be run before those of the current class,
  * unless they are overridden in the current class. No other ordering is defined.
- * </p>
- *
+ * <p>
  * Here is a simple example:
  * <pre>
  * public class Example {

src/main/java/org/junit/BeforeClass.java

@@ -6,13 +6,13 @@
 import java.lang.annotation.Target;
 
 /**
- * <p>Sometimes several tests need to share computationally expensive setup
+ * Sometimes several tests need to share computationally expensive setup
  * (like logging into a database). While this can compromise the independence of
  * tests, sometimes it is a necessary optimization. Annotating a <code>public static void</code> no-arg method
  * with <code>@BeforeClass</code> causes it to be run once before any of
  * the test methods in the class. The <code>@BeforeClass</code> methods of superclasses
- * will be run before those the current class, unless they are shadowed in the current class.</p>
- *
+ * will be run before those the current class, unless they are shadowed in the current class.
+ * <p>
  * For example:
  * <pre>
  * public class Example {

src/main/java/org/junit/ClassRule.java

@@ -8,31 +8,30 @@
 /**
  * Annotates static fields that reference rules or methods that return them. A field must be public,
  * static, and a subtype of {@link org.junit.rules.TestRule}.  A method must be public static, and return
- * a subtype of {@link org.junit.rules.TestRule}.<p>
- *
+ * a subtype of {@link org.junit.rules.TestRule}.
+ * <p>
  * The {@link org.junit.runners.model.Statement} passed
  * to the {@link org.junit.rules.TestRule} will run any {@link BeforeClass} methods,
  * then the entire body of the test class (all contained methods, if it is
  * a standard JUnit test class, or all contained classes, if it is a
  * {@link org.junit.runners.Suite}), and finally any {@link AfterClass} methods.
- *
+ * <p>
  * The statement passed to the {@link org.junit.rules.TestRule} will never throw an exception,
  * and throwing an exception from the {@link org.junit.rules.TestRule} will result in undefined
  * behavior.  This means that some {@link org.junit.rules.TestRule}s, such as
  * {@link org.junit.rules.ErrorCollector},
  * {@link org.junit.rules.ExpectedException},
  * and {@link org.junit.rules.Timeout},
  * have undefined behavior when used as {@link ClassRule}s.
- *
+ * <p>
  * If there are multiple
  * annotated {@link ClassRule}s on a class, they will be applied in an order
  * that depends on your JVM's implementation of the reflection API, which is
  * undefined, in general. However, Rules defined by fields will always be applied
  * before Rules defined by methods.
- *
+ * <p>
  * For example, here is a test suite that connects to a server once before
  * all the test classes run, and disconnects after they are finished:
- *
  * <pre>
  * &#064;RunWith(Suite.class)
  * &#064;SuiteClasses({A.class, B.class, C.class})
@@ -53,9 +52,8 @@
  *   };
  * }
  * </pre>
- *
+ * <p>
  * and the same using a method
- *
  * <pre>
  * &#064;RunWith(Suite.class)
  * &#064;SuiteClasses({A.class, B.class, C.class})
@@ -78,7 +76,7 @@
  *     }
  * }
  * </pre>
- *
+ * <p>
  * For more information and more examples, see {@link org.junit.rules.TestRule}.
  *
  * @since 4.9

src/main/java/org/junit/Ignore.java

@@ -6,12 +6,12 @@
 import java.lang.annotation.Target;
 
 /**
- * <p>Sometimes you want to temporarily disable a test or a group of tests. Methods annotated with
+ * Sometimes you want to temporarily disable a test or a group of tests. Methods annotated with
  * {@link org.junit.Test} that are also annotated with <code>&#064;Ignore</code> will not be executed as tests.
  * Also, you can annotate a class containing test methods with <code>&#064;Ignore</code> and none of the containing
  * tests will be executed. Native JUnit 4 test runners should report the number of ignored tests along with the
- * number of tests that ran and the number of tests that failed.</p>
- *
+ * number of tests that ran and the number of tests that failed.
+ * <p>
  * For example:
  * <pre>
  *    &#064;Ignore &#064;Test public void something() { ...

src/main/java/org/junit/Rule.java

@@ -10,8 +10,8 @@
  * static, and a subtype of {@link org.junit.rules.TestRule} (preferred) or
  * {@link org.junit.rules.MethodRule}. A method must be public, not static,
  * and must return a subtype of {@link org.junit.rules.TestRule} (preferred) or
- * {@link org.junit.rules.MethodRule}.<p>
- *
+ * {@link org.junit.rules.MethodRule}.
+ * <p>
  * The {@link org.junit.runners.model.Statement} passed
  * to the {@link org.junit.rules.TestRule} will run any {@link Before} methods,
  * then the {@link Test} method, and finally any {@link After} methods,
@@ -20,11 +20,10 @@
  * However, if there are mutliple fields (or methods) they will be applied in an order
  * that depends on your JVM's implementation of the reflection API, which is
  * undefined, in general. Rules defined by fields will always be applied
- * before Rules defined by methods.<p>
- *
+ * before Rules defined by methods.
+ * <p>
  * For example, here is a test class that creates a temporary folder before
  * each test method, and deletes it after each:
- *
  * <pre>
  * public static class HasTempFolder {
  *     &#064;Rule
@@ -38,9 +37,8 @@
  *     }
  * }
  * </pre>
- *
+ * <p>
  * And the same using a method.
- *
  * <pre>
  * public static class HasTempFolder {
  *     private TemporaryFolder folder= new TemporaryFolder();
@@ -58,7 +56,7 @@
  *     }
  * }
  * </pre>
- *
+ * <p>
  * For more information and more examples, see
  * {@link org.junit.rules.TestRule}.
  *

src/main/java/org/junit/Test.java

@@ -6,14 +6,14 @@
 import java.lang.annotation.Target;
 
 /**
- * <p>The <code>Test</code> annotation tells JUnit that the <code>public void</code> method
+ * The <code>Test</code> annotation tells JUnit that the <code>public void</code> method
  * to which it is attached can be run as a test case. To run the method,
  * JUnit first constructs a fresh instance of the class then invokes the
  * annotated method. Any exceptions thrown by the test will be reported
  * by JUnit as a failure. If no exceptions are thrown, the test is assumed
- * to have succeeded.</p>
- *
- * <p>A simple test looks like this:
+ * to have succeeded.
+ * <p>
+ * A simple test looks like this:
  * <pre>
  * public class Example {
  *    <b>&#064;Test</b>
@@ -22,9 +22,8 @@
  *    }
  * }
  * </pre>
- * </p>
- *
- * <p>The <code>Test</code> annotation supports two optional parameters.
+ * <p>
+ * The <code>Test</code> annotation supports two optional parameters.
  * The first, <code>expected</code>, declares that a test method should throw
  * an exception. If it doesn't throw an exception or if it throws a different exception
  * than the one declared, the test fails. For example, the following test succeeds:
@@ -33,14 +32,14 @@
  *       new ArrayList&lt;Object&gt;().get(1);
  *    }
  * </pre></p>
- *
- * <p>The second optional parameter, <code>timeout</code>, causes a test to fail if it takes
+ * <p>
+ * The second optional parameter, <code>timeout</code>, causes a test to fail if it takes
  * longer than a specified amount of clock time (measured in milliseconds). The following test fails:
  * <pre>
  *    &#064;Test(<b>timeout=100</b>) public void infinity() {
  *       while(true);
  *    }
- * </pre></p>
+ * </pre>
  *
  * @since 4.0
  */