Merge pull request junit-team#922 from AlexYursha/improve-theories-ja…

…vadoc

Add javadoc to some classes in org.junit.experimental.theories

src/main/java/org/junit/experimental/theories/ParameterSupplier.java

@@ -2,6 +2,42 @@
 
 import java.util.List;
 
+/**
+ * Abstract parent class for suppliers of input data points for theories. Extend this class to customize how {@link
+ * org.junit.experimental.theories.Theories Theories} runner
+ * finds accepted data points. Then use your class together with <b>&#064;ParametersSuppliedBy</b> on input
+ * parameters for theories.
+ *
+ * <p>
+ * For example, here is a supplier for values between two integers, and an annotation that references it:
+ *
+ * <pre>
+ *     &#064;Retention(RetentionPolicy.RUNTIME)
+ *     <b>&#064;ParametersSuppliedBy</b>(BetweenSupplier.class)
+ *     public @interface Between {
+ *         int first();
+ *
+ *         int last();
+ *     }
+ *
+ *     public static class BetweenSupplier extends <b>ParameterSupplier</b> {
+ *         &#064;Override
+ *         public List&lt;<b>PotentialAssignment</b>&gt; getValueSources(<b>ParameterSignature</b> sig) {
+ *             List&lt;<b>PotentialAssignment</b>&gt; list = new ArrayList&lt;PotentialAssignment&gt;();
+ *             Between annotation = (Between) sig.getSupplierAnnotation();
+ *
+ *             for (int i = annotation.first(); i &lt;= annotation.last(); i++)
+ *                 list.add(<b>PotentialAssignment</b>.forValue("ints", i));
+ *             return list;
+ *         }
+ *     }
+ * </pre>
+ * </p>
+ *
+ * @see org.junit.experimental.theories.ParametersSuppliedBy
+ * @see org.junit.experimental.theories.Theories
+ * @see org.junit.experimental.theories.FromDataPoints
+ */
 public abstract class ParameterSupplier {
     public abstract List<PotentialAssignment> getValueSources(ParameterSignature sig) throws Throwable;
 }

src/main/java/org/junit/experimental/theories/Theories.java

@@ -18,6 +18,56 @@
 import org.junit.runners.model.Statement;
 import org.junit.runners.model.TestClass;
 
+/**
+ * The Theories runner allows to test a certain functionality against a subset of an infinite set of data points.
+ * <p>
+ * A Theory is a piece of functionality (a method) that is executed against several data inputs called data points.
+ * To make a test method a theory you mark it with <b>&#064;Theory</b>. To create a data point you create a public
+ * field in your test class and mark it with <b>&#064;DataPoint</b>. The Theories runner then executes your test
+ * method as many times as the number of data points declared, providing a different data point as
+ * the input argument on each invocation.
+ * </p>
+ * <p>
+ * A Theory differs from standard test method in that it captures some aspect of the intended behavior in possibly
+ * infinite numbers of scenarios which corresponds to the number of data points declared. Using assumptions and
+ * assertions properly together with covering multiple scenarios with different data points can make your tests more
+ * flexible and bring them closer to scientific theories (hence the name).
+ * </p>
+ * <p>
+ * For example:
+ * <pre>
+ *
+ * &#064;RunWith(<b>Theories.class</b>)
+ * public class UserTest {
+ *      <b>&#064;DataPoint</b>
+ *      public static String GOOD_USERNAME = "optimus";
+ *      <b>&#064;DataPoint</b>
+ *      public static String USERNAME_WITH_SLASH = "optimus/prime";
+ *
+ *      <b>&#064;Theory</b>
+ *      public void filenameIncludesUsername(String username) {
+ *          assumeThat(username, not(containsString("/")));
+ *          assertThat(new User(username).configFileName(), containsString(username));
+ *      }
+ * }
+ * </pre>
+ * This makes it clear that the user's filename should be included in the config file name,
+ * only if it doesn't contain a slash. Another test or theory might define what happens when a username does contain
+ * a slash. <code>UserTest</code> will attempt to run <code>filenameIncludesUsername</code> on every compatible data
+ * point defined in the class. If any of the assumptions fail, the data point is silently ignored. If all of the
+ * assumptions pass, but an assertion fails, the test fails.
+ * <p>
+ * Defining general statements as theories allows data point reuse across a bunch of functionality tests and also
+ * allows automated tools to search for new, unexpected data points that expose bugs.
+ * </p>
+ * <p>
+ * The support for Theories has been absorbed from the Popper project, and more complete documentation can be found
+ * from that projects archived documentation.
+ * </p>
+ *
+ * @see <a href="http://web.archive.org/web/20071012143326/popper.tigris.org/tutorial.html">Archived Popper project documentation</a>
+ * @see <a href="http://web.archive.org/web/20110608210825/http://shareandenjoy.saff.net/tdd-specifications.pdf">Paper on Theories</a>
+ */
 public class Theories extends BlockJUnit4ClassRunner {
     public Theories(Class<?> klass) throws InitializationError {
         super(klass);

src/main/java/org/junit/experimental/theories/Theory.java

@@ -6,6 +6,11 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Marks test methods that should be read as theories by the {@link org.junit.experimental.theories.Theories Theories} runner.
+ *
+ * @see org.junit.experimental.theories.Theories
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(METHOD)
 public @interface Theory {

src/main/java/org/junit/experimental/theories/suppliers/TestedOnSupplier.java

@@ -7,6 +7,10 @@
 import org.junit.experimental.theories.ParameterSupplier;
 import org.junit.experimental.theories.PotentialAssignment;
 
+/**
+ * @see org.junit.experimental.theories.suppliers.TestedOn
+ * @see org.junit.experimental.theories.ParameterSupplier
+ */
 public class TestedOnSupplier extends ParameterSupplier {
     @Override
     public List<PotentialAssignment> getValueSources(ParameterSignature sig) {