Added JavaDoc to DataPoints and FromDataPoints

Author: pimterry

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

@@ -3,6 +3,43 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/**
+ * <p>
+ * Annotating an array-typed field or method with &#064;DataPoints will cause the
+ * values in the array (or returned array) to be used as potential parameters
+ * for theories in that class, when run with the
+ * {@link org.junit.experimental.theories.Theories Theories} runner.
+ * </p>
+ * <p>
+ * DataPoints will only be considered as potential values for parameters for
+ * which their types are assignable. When multiple sets of DataPoints exist with
+ * overlapping types more control can be obtained by naming the DataPoints using
+ * the value of this annotation, e.g. with
+ * <code>&#064;DataPoints({"dataset1", "dataset2"})</code>, and then specifying
+ * which named set to consider as potential values for each parameter using the
+ * {@link org.junit.experimental.theories.FromDataPoints &#064;FromDataPoints}
+ * annotation.
+ * </p>
+ * 
+ * <pre>
+ * &#064;DataPoints
+ * public static String[] dataPoints = new String[] { ... };
+ * 
+ * &#064;DataPoints
+ * public static String[] generatedDataPoints() {
+ *     return new String[] { ... };
+ * }
+ * 
+ * &#064;Theory
+ * public void theoryMethod(String param) {
+ *     ...
+ * }</pre>
+ * 
+ * @see org.junit.experimental.theories.Theories
+ * @see org.junit.experimental.theories.Theory
+ * @see org.junit.experimental.theories.DataPoint
+ * @see org.junit.experimental.theories.FromDataPoints
+ */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface DataPoints {
     String[] value() default {};

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

@@ -7,6 +7,43 @@
 
 import org.junit.experimental.theories.internal.SpecificDataPointsSupplier;
 
+/**
+ * <p>
+ * Annotating a parameter of a {@link org.junit.experimental.theories.Theory
+ * &#064Theory} method with <code>&#064;FromDataPoints</code> will limit the
+ * datapoints considered as potential values for that parameter to just the
+ * {@link org.junit.experimental.theories.DataPoints DataPoints} with the 
+ * given name. For example:
+ * </p>
+ * 
+ * <pre>
+ * &#064;DataPoints
+ * public static String[] unnamed = new String[] { ... };
+ * 
+ * &#064;DataPoints("regexes")
+ * public static String[] regexStrings = new String[] { ... };
+ * 
+ * &#064;DataPoints({"forMatching", "alphanumeric"})
+ * public static String[] testStrings = new String[] { ... }; 
+ * 
+ * &#064;Theory
+ * public void stringTheory(String param) {
+ *     // This will be called with every value in 'regexStrings',
+ *     // 'testStrings' and 'unnamed'.
+ * }
+ * 
+ * &#064;Theory
+ * public void regexTheory(&#064;FromDataPoints("regexes") String regex,
+ *                         &#064;FromDataPoints("forMatching") String value) {
+ *     // This will be called with only the values in 'regexStrings' as 
+ *     // regex, only the values in 'testStrings' as value, and none 
+ *     // of the values in 'unnamed'.
+ * }</pre>
+ * 
+ * @see org.junit.experimental.theories.Theory
+ * @see org.junit.experimental.theories.DataPoint
+ * @see org.junit.experimental.theories.DataPoints
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.PARAMETER)
 @ParametersSuppliedBy(SpecificDataPointsSupplier.class)