adding documentation.

git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@20612 71c3de6d-444a-0410-be80-ed276b4c234a

core/src/main/java/hudson/tasks/junit/JUnitResultArchiver.java

@@ -79,12 +79,15 @@ public class JUnitResultArchiver extends Recorder implements Serializable,
 	 */
 	private final String testResults;
 
+    /**
+     * {@link TestDataPublisher}s configured for this archiver, to process the recorded data.
+     * For compatibility reasons, can be null.
+     * @since 1.320
+     */
 	private final DescribableList<TestDataPublisher, Descriptor<TestDataPublisher>> testDataPublishers;
 
 	/**
 	 * left for backwards compatibility
-	 * 
-	 * @param testResults
 	 */
 	@Deprecated
 	public JUnitResultArchiver(String testResults) {
@@ -115,8 +118,7 @@ public class JUnitResultArchiver extends Recorder implements Serializable,
 
 			action = new TestResultAction(build, result, listener);
 			if (result.getPassCount() == 0 && result.getFailCount() == 0)
-				throw new AbortException(Messages
-						.JUnitResultArchiver_ResultIsEmpty());
+				throw new AbortException(Messages.JUnitResultArchiver_ResultIsEmpty());
 
 			List<Data> data = new ArrayList<Data>();
 			if (testDataPublishers != null) {
@@ -205,15 +207,13 @@ public class JUnitResultArchiver extends Recorder implements Serializable,
 		private final String testResults;
 		private final long nowMaster;
 
-		private ParseResultCallable(String testResults, long buildTime, 
-				long nowMaster) {
+		private ParseResultCallable(String testResults, long buildTime, long nowMaster) {
 			this.buildTime = buildTime;
 			this.testResults = testResults;
 			this.nowMaster = nowMaster;
 		}
 
-		public TestResult invoke(File ws, VirtualChannel channel)
-				throws IOException {
+		public TestResult invoke(File ws, VirtualChannel channel) throws IOException {
 			final long nowSlave = System.currentTimeMillis();
 
 			FileSet fs = Util.createFileSet(ws, testResults);
@@ -223,9 +223,7 @@ public class JUnitResultArchiver extends Recorder implements Serializable,
 			if (files.length == 0) {
 				// no test result. Most likely a configuration
 				// error or fatal problem
-				throw new AbortException(
-						Messages
-								.JUnitResultArchiver_NoTestReportFound());
+				throw new AbortException(Messages.JUnitResultArchiver_NoTestReportFound());
 			}
 
 			return new TestResult(buildTime + (nowSlave - nowMaster), ds);

core/src/main/java/hudson/tasks/junit/TabulatedResult.java

@@ -39,8 +39,10 @@ public abstract class TabulatedResult extends TestObject {
 
     /**
      * Gets the child test result objects.
+     *
+     * @see TestObject#getParent()
      */
-    public abstract Collection<?> getChildren();
+    public abstract Collection<? extends TestObject> getChildren();
 
     /**
      * Gets the name of this object.

core/src/main/java/hudson/tasks/junit/TestDataPublisher.java

+/*
+ * The MIT License
+ *
+ * Copyright (c) 2004-2009, Sun Microsystems, Inc., Tom Huybrechts
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package hudson.tasks.junit;
 
 import java.io.IOException;
@@ -5,15 +28,32 @@ import java.io.IOException;
 import hudson.DescriptorExtensionList;
 import hudson.ExtensionPoint;
 import hudson.Launcher;
+import hudson.Extension;
 import hudson.model.AbstractBuild;
 import hudson.model.BuildListener;
 import hudson.model.Describable;
 import hudson.model.Descriptor;
 import hudson.model.Hudson;
 
-public abstract class TestDataPublisher implements
-		Describable<TestDataPublisher>, ExtensionPoint {
+/**
+ * Contributes {@link TestAction}s to test results.
+ *
+ * This enables plugins to annotate test results and provide richer UI, such as letting users
+ * claim test failures, allowing people to file bugs, or more generally, additional actions, views, etc.
+ *
+ * <p>
+ * To register your implementation, put {@link Extension} on your descriptor implementation. 
+ *
+ * @since 1.320
+ */
+public abstract class TestDataPublisher implements Describable<TestDataPublisher>, ExtensionPoint {
 
+    /**
+     * Called after test results are collected by Hudson, to create a resolver for {@link TestAction}s.
+     *
+     * @return
+     *      can be null to indicate that there's nothing to contribute for this test result.
+     */
 	public abstract TestResultAction.Data getTestData(
 			AbstractBuild<?, ?> build, Launcher launcher,
 			BuildListener listener, TestResult testResult) throws IOException, InterruptedException;
@@ -24,8 +64,7 @@ public abstract class TestDataPublisher implements
 	}
 
 	public static DescriptorExtensionList<TestDataPublisher, Descriptor<TestDataPublisher>> all() {
-		return Hudson.getInstance().getDescriptorList(
-				TestDataPublisher.class);
+		return Hudson.getInstance().getDescriptorList(TestDataPublisher.class);
 	}
 
 }

core/src/main/java/hudson/tasks/junit/TestObject.java

@@ -74,12 +74,15 @@ import org.kohsuke.stapler.export.ExportedBean;
  */
 @ExportedBean
 public abstract class TestObject extends AbstractModelObject implements Serializable {
-	public AbstractBuild<?, ?> getOwner() {
-		return getParent().getOwner();
-	}
-
 	private volatile transient String id;
 
+    public AbstractBuild<?,?> getOwner() {
+        return getParent().getOwner();
+    }
+
+    /**
+     * Reverse pointer of {@link TabulatedResult#getChildren()}.
+     */
 	public abstract TestObject getParent();
 
 	public String getId() {

core/src/main/java/hudson/tasks/junit/TestResultAction.java

@@ -183,7 +183,10 @@ public class TestResultAction extends AbstractTestResultAction<TestResultAction>
     
     public static abstract class Data {
     	/**
-    	 * Returns all TestActions for the testObject. Always non-null
+    	 * Returns all TestActions for the testObject.
+         * 
+         * @return
+         *      Can be empty but never null. The caller must assume that the returned list is read-only.
     	 */
     	public abstract List<TestAction> getTestAction(TestObject testObject);
     }