Browse files

Patched javadoc, thanks to Matthias Schmidt

RunWith is @Inherited
Added acknowledgements
to-do is up to date
  • Loading branch information...
1 parent 23ab517 commit 65d6b62dd60c434447544c5419ef4eeecb4c645d dsaff committed Mar 10, 2006
View
2 acknowledgements.txt
@@ -0,0 +1,2 @@
+2006 March 9
+ Matthias Schmidt: improved org.junit package javadoc
View
2 build.xml
@@ -1,6 +1,6 @@
<project name="junit" default="dist" basedir=".">
<property file="${user.home}/.junit.properties" />
- <property name="version" value="4.0" />
+ <property name="version" value="4.1" />
<property name="dist" value="junit${version}" />
<property name="versionfile" value="junit/runner/Version.java" />
<property name="zipfile" value="${dist}.zip" />
View
9 done.txt
@@ -39,5 +39,12 @@
* make sure TestListener is symmetric and meets needs of runner developers
* TestRunEvent
* Decide how we ship JUnit-- 1.5 only or hybrid
-
+ * README.html
+* add javadoc to API interfaces and Annotations
+ http://java.sun.com/j2se/javadoc/writingapispecs/index.html
+* Merge branch back into head
+* review Ant scripts
+* make suites simpler for both the IDE providers and the users
+* ClassRequest should search up the hierarchy for the requested Class to look for @RunWith
+
View
2 junit/runner/Version.java
@@ -9,7 +9,7 @@ private Version() {
}
public static String id() {
- return "4.0";
+ return "4.1";
}
public static void main(String[] args) {
View
7 org/junit/After.java
@@ -6,10 +6,10 @@
import java.lang.annotation.Target;
/**
- * If you allocate external resources in a <code>@Before</code> 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>@After</code> causes that method to be run after the <code>@Test</code> method. All <code>@After</code>
- * methods are guaranteed to run even if a <code>@Before</code> or <code>@Test</code> method throws an
+ * with <code>@After</code> causes that method to be run after the {@link org.junit.Test} method. All <code>@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>@After</code> methods declared in superclasses will be run after those of the current
* class.
* <p>
@@ -30,6 +30,7 @@
* </code>
*
* @see org.junit.Before
+ * @see org.junit.Test
*/
@Retention(RetentionPolicy.RUNTIME)
View
5 org/junit/AfterClass.java
@@ -6,10 +6,10 @@
import java.lang.annotation.Target;
/**
- * If you allocate expensive external resources in a <code>@BeforeClass</code> 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>@AfterClass</code> causes that method to be run after all the tests in the class have been run. All <code>@AfterClass</code>
- * methods are guaranteed to run even if a <code>@BeforeClass</code> method throws an
+ * methods are guaranteed to run even if a {@link org.junit.BeforeClass} method throws an
* exception. The <code>@AfterClass</code> methods declared in superclasses will be run after those of the current
* class.
* <p>
@@ -33,6 +33,7 @@
* </code>
*
* @see org.junit.BeforeClass
+ * @see org.junit.Test
*/
@Retention(RetentionPolicy.RUNTIME)
View
115 org/junit/Assert.java
@@ -9,18 +9,23 @@
* ...<br>
* &nbsp;&nbsp;assertEquals(...);<br>
* </code>
+ *
+ * @see java.lang.AssertionError
*/
-
public class Assert {
/**
* Protect constructor since it is a static only class
*/
protected Assert() {
}
+
+ // TODO: param comments should start with lower case letters
/**
* Asserts that a condition is true. If it isn't it throws an
- * AssertionError with the given message.
+ * {@link AssertionError} with the given message.
+ * @param message the identifying message or <code>null</code> for the {@link AssertionError}
+ * @param condition condition to be checked
*/
static public void assertTrue(String message, boolean condition) {
if (!condition)
@@ -29,30 +34,36 @@ static public void assertTrue(String message, boolean condition) {
/**
* Asserts that a condition is true. If it isn't it throws an
- * AssertionError.
+ * {@link AssertionError} without a message.
+ * @param condition condition to be checked
*/
static public void assertTrue(boolean condition) {
assertTrue(null, condition);
}
/**
* Asserts that a condition is false. If it isn't it throws an
- * AssertionError with the given message.
+ * {@link AssertionError} with the given message.
+ * @param message the identifying message or <code>null</code> for the {@link AssertionError}
+ * @param condition condition to be checked
*/
static public void assertFalse(String message, boolean condition) {
assertTrue(message, !condition);
}
/**
* Asserts that a condition is false. If it isn't it throws an
- * AssertionError.
+ * {@link AssertionError} without a message.
+ * @param condition condition to be checked
*/
static public void assertFalse(boolean condition) {
assertFalse(null, condition);
}
/**
* Fails a test with the given message.
+ * @param message the identifying message or <code>null</code> for the {@link AssertionError}
+ * @see AssertionError
*/
static public void fail(String message) {
throw new AssertionError(message);
@@ -67,7 +78,10 @@ static public void fail() {
/**
* Asserts that two objects are equal. If they are not, an
- * AssertionError is thrown with the given message.
+ * {@link AssertionError} is thrown with the given message.
+ * @param message the identifying message or <code>null</code> for the {@link AssertionError}
+ * @param expected expected value
+ * @param actual actual value
*/
static public void assertEquals(String message, Object expected, Object actual) {
if (expected == null && actual == null)
@@ -82,15 +96,20 @@ static public void assertEquals(String message, Object expected, Object actual)
/**
* Asserts that two objects are equal. If they are not, an
- * AssertionError is thrown.
+ * {@link AssertionError} without a message is thrown.
+ * @param expected expected value
+ * @param actual the value to check against <code>expected</code>
*/
static public void assertEquals(Object expected, Object actual) {
assertEquals(null, expected, actual);
}
/**
* Asserts that two object arrays are equal. If they are not, an
- * AssertionError is thrown with the given message.
+ * {@link AssertionError} is thrown with the given message.
+ * @param message the identifying message or <code>null</code> for the {@link AssertionError}
+ * @param expecteds Object array or array of arrays (multi-dimensional array) with expected values
+ * @param actuals Object array or array of arrays (multi-dimensional array) with actual values
*/
public static void assertEquals(String message, Object[] expecteds, Object[] actuals) {
if (expecteds == actuals)
@@ -117,18 +136,25 @@ public static void assertEquals(String message, Object[] expecteds, Object[] act
/**
* Asserts that two object arrays are equal. If they are not, an
- * AssertionError is thrown.
+ * {@link AssertionError} is thrown.
+ * @param expecteds Object array or array of arrays (multi-dimensional array) with expected values
+ * @param actuals Object array or array of arrays (multi-dimensional array) with actual values
*/
public static void assertEquals(Object[] expecteds, Object[] actuals) {
assertEquals(null, expecteds, actuals);
}
/**
* Asserts that two doubles are equal to within a positive delta. If they
- * are not, an AssertionError is thrown with the given message. If the
+ * are not, an {@link AssertionError} is thrown with the given message. If the
* expected value is infinity then the delta value is ignored. NaNs are
* considered equal:
- * assertEquals(Double.NaN, Double.NaN, *) passes
+ * <code>assertEquals(Double.NaN, Double.NaN, *)</code> passes
+ * @param message the identifying message or <code>null</code> for the {@link AssertionError}
+ * @param expected expected value
+ * @param actual the value to check against <code>expected</code>
+ * @param delta the maximum delta between <code>expected</code> and <code>actual</code> for which
+ * both numbers are still considered equal.
*/
static public void assertEquals(String message, double expected, double actual, double delta) {
if (Double.compare(expected, actual) == 0)
@@ -139,21 +165,30 @@ static public void assertEquals(String message, double expected, double actual,
/**
* Asserts that two doubles are equal to within a positive delta. If they
- * are not, an AssertionError is thrown. If the
+ * are not, an {@link AssertionError} is thrown. If the
* expected value is infinity then the delta value is ignored.NaNs are
* considered equal:
- * assertEquals(Double.NaN, Double.NaN, *) passes
+ * <code>assertEquals(Double.NaN, Double.NaN, *)</code> passes
+ * @param expected expected value
+ * @param actual the value to check against <code>expected</code>
+ * @param delta the maximum delta between <code>expected</code> and <code>actual</code> for which
+ * both numbers are still considered equal.
*/
static public void assertEquals(double expected, double actual, double delta) {
assertEquals(null, expected, actual, delta);
}
/**
* Asserts that two floats are equal to within a positive delta. If they
- * are not, an AssertionError is thrown with the given message. If the
+ * are not, an {@link AssertionError} is thrown with the given message. If the
* expected value is infinity then the delta value is ignored.NaNs are
* considered equal:
- * assertEquals(Float.NaN, Float.NaN, *) passes
+ * <code>assertEquals(Float.NaN, Float.NaN, *)</code> passes
+ * @param message the identifying message or <code>null</code> for the {@link AssertionError}
+ * @param expected the expected float value
+ * @param actual the float value to check against <code>expected</code>
+ * @param delta the maximum delta between <code>expected</code> and <code>actual</code> for which
+ * both numbers are still considered equal.
*/
static public void assertEquals(String message, float expected, float actual, float delta) {
if (Float.compare(expected, actual) == 0)
@@ -164,50 +199,63 @@ static public void assertEquals(String message, float expected, float actual, fl
/**
* Asserts that two floats are equal to within a positive delta. If they
- * are not, an AssertionError is thrown. If the
- * expected value is infinity then the delta value is ignored.NaNs are
+ * are not, an {@link AssertionError} is thrown. If the
+ * expected value is infinity then the delta value is ignored. {@link Float#NaN NaNs} are
* considered equal:
- * assertEquals(Float.NaN, Float.NaN, *) passes
+ * <code>assertEquals(Float.NaN, Float.NaN, *)</code> passes
+ * @param expected the expected value
+ * @param actual the value to check against <code>expected</code>
+ * @param delta the maximum delta between <code>expected</code> and <code>actual</code> for which
+ * both numbers are still considered equal.
*/
static public void assertEquals(float expected, float actual, float delta) {
assertEquals(null, expected, actual, delta);
}
/**
- * Asserts that an object isn't null. If it is an AssertionError is
+ * Asserts that an object isn't null. If it is an {@link AssertionError} is
* thrown with the given message.
+ * @param message the identifying message or <code>null</code> for the {@link AssertionError}
+ * @param object Object to check or <code>null</code>
*/
static public void assertNotNull(String message, Object object) {
assertTrue(message, object != null);
}
/**
- * Asserts that an object isn't null. If it is an AssertionError is
+ * Asserts that an object isn't null. If it is an {@link AssertionError} is
* thrown.
+ * @param object Object to check or <code>null</code>
*/
static public void assertNotNull(Object object) {
assertNotNull(null, object);
}
/**
- * Asserts that an object is null. If it is not, an AssertionError is
+ * Asserts that an object is null. If it is not, an {@link AssertionError} is
* thrown with the given message.
+ * @param message the identifying message or <code>null</code> for the {@link AssertionError}
+ * @param object Object to check or <code>null</code>
*/
static public void assertNull(String message, Object object) {
assertTrue(message, object == null);
}
/**
- * Asserts that an object is null. If it isn't an AssertionError is
+ * Asserts that an object is null. If it isn't an {@link AssertionError} is
* thrown.
+ * @param object Object to check or <code>null</code>
*/
static public void assertNull(Object object) {
assertNull(null, object);
}
/**
* Asserts that two objects refer to the same object. If they are not, an
- * AssertionError is thrown with the given message.
+ * {@link AssertionError} is thrown with the given message.
+ * @param message the identifying message or <code>null</code> for the {@link AssertionError}
+ * @param expected the expected object
+ * @param actual the object to compare to <code>expected</code>
*/
static public void assertSame(String message, Object expected, Object actual) {
if (expected == actual)
@@ -217,28 +265,35 @@ static public void assertSame(String message, Object expected, Object actual) {
/**
* Asserts that two objects refer to the same object. If they are not the
- * same, an AssertionError is thrown.
+ * same, an {@link AssertionError} without a message is thrown.
+ * @param expected the expected object
+ * @param actual the object to compare to <code>expected</code>
*/
static public void assertSame(Object expected, Object actual) {
assertSame(null, expected, actual);
}
/**
* Asserts that two objects do not refer to the same object. If they do
- * refer to the same object, an AssertionError is thrown with the given
+ * refer to the same object, an {@link AssertionError} is thrown with the given
* message.
+ * @param message the identifying message or <code>null</code> for the {@link AssertionError}
+ * @param unexpected the object you don't expect
+ * @param actual the object to compare to <code>unexpected</code>
*/
- static public void assertNotSame(String message, Object expected, Object actual) {
- if (expected == actual)
+ static public void assertNotSame(String message, Object unexpected, Object actual) {
+ if (unexpected == actual)
failSame(message);
}
/**
* Asserts that two objects do not refer to the same object. If they do
- * refer to the same object, an AssertionError is thrown.
+ * refer to the same object, an {@link AssertionError} without a message is thrown.
+ * @param unexpected the object you don't expect
+ * @param actual the object to compare to <code>unexpected</code>
*/
- static public void assertNotSame(Object expected, Object actual) {
- assertNotSame(null, expected, actual);
+ static public void assertNotSame(Object unexpected, Object actual) {
+ assertNotSame(null, unexpected, actual);
}
static private void failSame(String message) {
View
2 org/junit/Before.java
@@ -8,7 +8,7 @@
/**
* 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>@Before</code> causes that method to be run before the <code>@Test</code> method.
+ * with <code>@Before</code> causes that method to be run before the {@link org.junit.Test} method.
* The <code>@Before</code> methods of superclasses will be run before those of the current class.
* <p>
* Here is a simple example:
View
6 org/junit/ComparisonFailure.java
@@ -1,7 +1,7 @@
package org.junit;
/**
- * Thrown when an assertEquals(String, String) fails. Create and throw
+ * Thrown when an {@link org.junit.Assert#assertEquals(Object, Object) assertEquals(String, String)} fails. Create and throw
* a <code>ComparisonFailure</code> manually if you want to show users the difference between two complex
* strings.
*
@@ -38,14 +38,14 @@ public String getMessage() {
}
/**
- * Returns the actual value
+ * Returns the actual string value
* @return the actual string value
*/
public String getActual() {
return fActual;
}
/**
- * Returns the expected value
+ * Returns the expected string value
* @return the expected string value
*/
public String getExpected() {
View
10 org/junit/runner/RunWith.java
@@ -1,21 +1,25 @@
package org.junit.runner;
import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
-//TODO add simple exampel
+//TODO add simple example
/**
- * When you annotate a class with <code>@RunWith</code>, JUnit will invoke
+ * When a class is annotated with <code>@RunWith</code> or extends a class annotated with
+ * <code>@RunWith</code>,
+ * JUnit will invoke
* the class it references to run the tests in that class instead of the runner
- * built into JUnit. We added this feature late in development. While it
+ * built into JUnit. We added this feature late in development. While it
* seems powerful we expect the runner API to change as we learn how people
* really use it. Some of the classes that are currently internal will likely be refined
* and become public.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
+@Inherited
public @interface RunWith {
/**
* @return a Runner class (must have a constructor that takes a single Class to run)
View
11 org/junit/tests/RunWithTest.java
@@ -48,6 +48,17 @@ public Description getDescription() {
assertTrue(log.contains("initialize"));
assertTrue(log.contains("run"));
}
+
+ public static class SubExampleTest extends ExampleTest {
+ }
+
+ @Test public void runWithExtendsToSubclasses() {
+ log= "";
+
+ JUnitCore.runClasses(SubExampleTest.class);
+ assertTrue(log.contains("run"));
+ }
+
public static junit.framework.Test suite() {
return new JUnit4TestAdapter(RunWithTest.class);
View
14 to-do.txt
@@ -1,26 +1,18 @@
-Before first public release:
* update documentation
* new cook's tour
* update Test Infected
- * README.html
-* add javadoc to API interfaces and Annotations
- http://java.sun.com/j2se/javadoc/writingapispecs/index.html
-* review Ant scripts
-* Merge branch back into head
-* ClassRequest should search up the hierarchy for the requested Class to look for @RunWith
* Should there be a "prefix" annotation for Suites?
* This would allow two Suites with different BeforeClass/AfterClass behaviors,
but the same component tests, to co-exist
-Before next JUnit 4 release:
* update the build process
* automatically upload a new JAR
* update site for plug-in version?
-* make suites simpler for both the IDE providers and the users
-* class level test annotations?
* Ant
* Basic task
* support testing run once initialization code e.g. class Foo {{...}}
* Automatically add failing tests to the Known Defects section of the README.html
-
+* Create test target in ant
+* Organize org.junit.tests
+* Use <pre></pre> for javadoc code examples

0 comments on commit 65d6b62

Please sign in to comment.