Done with interceptor javadoc

.settings/org.eclipse.jdt.core.prefs

@@ -1,4 +1,4 @@
-#Tue Jul 07 23:32:42 EDT 2009
+#Tue Jul 07 23:38:50 EDT 2009
 eclipse.preferences.version=1
 org.eclipse.jdt.core.codeComplete.argumentPrefixes=
 org.eclipse.jdt.core.codeComplete.argumentSuffixes=
@@ -46,7 +46,7 @@ org.eclipse.jdt.core.compiler.problem.localVariableHiding=ignore
 org.eclipse.jdt.core.compiler.problem.methodWithConstructorName=warning
 org.eclipse.jdt.core.compiler.problem.missingDeprecatedAnnotation=warning
 org.eclipse.jdt.core.compiler.problem.missingHashCodeMethod=ignore
-org.eclipse.jdt.core.compiler.problem.missingJavadocComments=ignore
+org.eclipse.jdt.core.compiler.problem.missingJavadocComments=warning
 org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsOverriding=disabled
 org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsVisibility=protected
 org.eclipse.jdt.core.compiler.problem.missingJavadocTagDescription=no_tag

src/main/java/org/junit/experimental/interceptor/ExpectedException.java

@@ -43,6 +43,10 @@
  * </pre>
  */
 public class ExpectedException implements MethodRule {
+	/**
+	 * @return a Rule that expects no exception to be thrown
+	 * (identical to behavior without this Rule)
+	 */
 	public static ExpectedException none() {
 		return new ExpectedException();
 	}

src/main/java/org/junit/experimental/interceptor/MethodRule.java

@@ -3,8 +3,37 @@
 import org.junit.runners.model.FrameworkMethod;
 import org.junit.runners.model.Statement;
 
+/**
+ * A MethodRule is an alteration in how a test method is run and reported.
+ * Multiple {@link MethodRule}s can be applied to a test method. The
+ * {@link Statement} that executes the method is passed to each annotated
+ * {@link Rule} in turn, and each may return a substitute or modified
+ * {@link Statement}, which is passed to the next {@link Rule}, if any. For
+ * examples of how this can be useful, see these provided MethodRules,
+ * or write your own:
+ * 
+ * <ul>
+ *   <li>{@link ErrorCollector}: collect multiple errors in one test method</li>
+ *   <li>{@link ExpectedException}: make flexible assertions about thrown exceptions</li>
+ *   <li>{@link ExternalResource}: start and stop a server, for example</li>
+ *   <li>{@link TemporaryFolder}: create fresh files, and delete after test</li>
+ *   <li>{@link TestName}: remember the test name for use during the method</li>
+ *   <li>{@link TestWatchman}: add logic at events during method execution</li>
+ *   <li>{@link Timeout}: cause test to fail after a set time</li>
+ *   <li>{@link Verifier}: fail test if object state ends up incorrect</li>
+ * </ul>
+ */
 public interface MethodRule {
-	// TODO (Jul 1, 2009 1:43:11 PM): add documentation to
-	// BlockJUnit4ClassRunner
+	// TODO (Jul 7, 2009 11:57:15 PM): Fix interceptor test names.
+	/**
+	 * Modifies the method-running {@link Statement} to implement an additional
+	 * test-running rule.
+	 * 
+	 * @param base The {@link Statement} to be modified
+	 * @param method The method to be run
+	 * @param target The object on with the method will be run.
+	 * @return a new statement, which may be the same as {@code base},
+	 * a wrapper around {@code base}, or a completely new Statement.
+	 */
 	Statement apply(Statement base, FrameworkMethod method, Object target);
 }

src/main/java/org/junit/experimental/interceptor/TemporaryFolder.java

@@ -36,28 +36,45 @@ protected void after() {
 	}
 
 	// testing purposes only
+	/**
+	 * for testing purposes only.  Do not use.
+	 */
 	public void create() throws IOException {
 		folder= File.createTempFile("junit", "");
 		folder.delete();
 		folder.mkdir();
 	}
 
+	/**
+	 * Returns a new fresh file with the given name under the temporary folder.
+	 */
 	public File newFile(String fileName) throws IOException {
 		File file= new File(folder, fileName);
 		file.createNewFile();
 		return file;
 	}
 
+	/**
+	 * Returns a new fresh folder with the given name under the temporary folder.
+	 */
 	public File newFolder(String folderName) {
 		File file= new File(folder, folderName);
 		file.mkdir();
 		return file;
 	}
 
+	/**
+	 * @return the location of this temporary folder.
+	 */
 	public File getRoot() {
 		return folder;
 	}
 
+	/**
+	 * Delete all files and folders under the temporary folder.
+	 * Usually not called directly, since it is automatically applied 
+	 * by the {@link Rule}
+	 */
 	public void delete() {
 		recursiveDelete(folder);
 	}

src/main/java/org/junit/experimental/interceptor/TestName.java

@@ -30,6 +30,9 @@ public void starting(FrameworkMethod method) {
 		fName= method.getName();
 	}
 
+	/**
+	 * @return the name of the currently-running test method
+	 */
 	public String getMethodName() {
 		return fName;
 	}

src/main/java/org/junit/experimental/interceptor/Timeout.java

@@ -36,6 +36,9 @@
 public class Timeout implements MethodRule {
 	private final int fMillis;
 
+	/**
+	 * @param millis the millisecond timeout
+	 */
 	public Timeout(int millis) {
 		fMillis= millis;
 	}

src/main/java/org/junit/experimental/interceptor/Verifier.java

@@ -37,6 +37,10 @@ public void evaluate() throws Throwable {
 		};
 	}
 
+	/**
+	 * Override this to add verification logic. Overrides should throw an
+	 * exception to indicate that verification failed.
+	 */
 	protected void verify() throws Throwable {
 	}
 }

src/main/java/org/junit/experimental/max/MaxHistory.java

@@ -31,9 +31,6 @@ public class MaxHistory implements Serializable {
 	 * will be saved to {@code file}.
 	 */
 	public static MaxHistory forFolder(File file) {
-		// TODO: temp!
-		if (file.getPath() == null)
-			throw new NullPointerException();
 		if (file.exists())
 			try {
 				return readHistory(file);

src/main/java/org/junit/runners/BlockJUnit4ClassRunner.java

@@ -222,6 +222,10 @@ protected String testName(FrameworkMethod method) {
 	 * <li>HOWEVER, if {@code method}'s {@code @Test} annotation has the {@code
 	 * timeout} attribute, throw an exception if the previous step takes more
 	 * than the specified number of milliseconds.
+	 * <li>ALWAYS allow {@code @Rule} fields to modify the execution of the above
+	 * steps.  A {@code Rule} may prevent all execution of the above steps, or
+	 * add additional behavior before and after, or modify thrown exceptions.
+	 * For more information, see {@link MethodRule}
 	 * <li>ALWAYS run all non-overridden {@code @Before} methods on this class
 	 * and superclasses before any of the previous steps; if any throws an
 	 * Exception, stop execution and pass the exception on.