Polish JavaDoc for parameterized tests

sbrannen · marcphilipp · commit f256dc599ceb · 2017-04-01T10:25:45.000+02:00
Issue: #14
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedTest.java
@@ -37,7 +37,7 @@
  * {@link org.junit.jupiter.api.extension.ParameterResolver ParameterResolvers}
  * at the end of the method's parameter list.
  *
- * <p>Method parameters may use the
+ * <p>Method parameters may use
  * {@link org.junit.jupiter.params.converter.ConvertWith @ConvertWith}
  * or a corresponding composed annotation to specify an explicit
  * {@link org.junit.jupiter.params.converter.ArgumentConverter}.
@@ -48,14 +48,14 @@
  *
  * <p>{@code @ParameterizedTest} methods must not be {@code private} or {@code static}.
  *
+ * @since 5.0
  * @see org.junit.jupiter.params.provider.ArgumentsSource
  * @see org.junit.jupiter.params.provider.CsvFileSource
  * @see org.junit.jupiter.params.provider.CsvSource
  * @see org.junit.jupiter.params.provider.EnumSource
  * @see org.junit.jupiter.params.provider.MethodSource
  * @see org.junit.jupiter.params.provider.ValueSource
  * @see org.junit.jupiter.params.converter.ConvertWith
- * @since 5.0
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/ArgumentConversionException.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/ArgumentConversionException.java
@@ -16,12 +16,12 @@
 import org.junit.platform.commons.meta.API;
 
 /**
- * {@code @ArgumentConversionException} is an exception that can
+ * {@code ArgumentConversionException} is an exception that can
  * occur when an object is converted to another object by an implementation
  * of an {@code org.junit.jupiter.params.converter.ArgumentConverter}.
  *
- * @see org.junit.jupiter.params.converter.ArgumentConverter
  * @since 5.0
+ * @see org.junit.jupiter.params.converter.ArgumentConverter
  */
 @API(Experimental)
 public class ArgumentConversionException extends JUnitException {
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/ArgumentConverter.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/ArgumentConverter.java
@@ -16,16 +16,17 @@
 import org.junit.platform.commons.meta.API;
 
 /**
- * {@code @ArgumentConverter} is an abtraction that allows an input object to
+ * {@code ArgumentConverter} is an abstraction that allows an input object to
  * be converted to an instance of a different class.
  *
- * Such an {@code @ArgumentConverter} is applied to the method parameter
- * of a {@link org.junit.jupiter.params.ParameterizedTest} method with the help of an
- * {@link org.junit.jupiter.params.converter.ConvertWith} annotation.
+ * <p>Such an {@code ArgumentConverter} is applied to the method parameter
+ * of a {@link org.junit.jupiter.params.ParameterizedTest @ParameterizedTest}
+ * method with the help of a
+ * {@link org.junit.jupiter.params.converter.ConvertWith @ConvertWith} annotation.
  *
+ * @since 5.0
  * @see org.junit.jupiter.params.ParameterizedTest
  * @see org.junit.jupiter.params.converter.ConvertWith
- * @since 5.0
  */
 @API(Experimental)
 public interface ArgumentConverter {
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/ConvertWith.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/ConvertWith.java
@@ -18,20 +18,19 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.platform.commons.meta.API;
 
 /**
- * {@code @ConvertWith} is an annotation that allows to to specify an explicit
+ * {@code @ConvertWith} is an annotation that allows one to specify an explicit
  * {@link org.junit.jupiter.params.converter.ArgumentConverter}.
 
  * <p>This annotation may be applied to method parameters of
- * {@link ParameterizedTest} methods which need to have their {@code Arguments}
- * converted before consuming them.
+ * {@link org.junit.jupiter.params.ParameterizedTest @ParameterizedTest} methods
+ * which need to have their {@code Arguments} converted before consuming them.
  *
+ * @since 5.0
  * @see org.junit.jupiter.params.ParameterizedTest
  * @see org.junit.jupiter.params.converter.ArgumentConverter
- * @since 5.0
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.PARAMETER })
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/DefaultArgumentConverter.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/DefaultArgumentConverter.java
@@ -36,17 +36,19 @@
 import org.junit.platform.commons.util.ReflectionUtils;
 
 /**
- * {@code @DefaultArgumentConverter} is the default implementation for the
- * {@code @ArgumentConverter} abstraction.
+ * {@code DefaultArgumentConverter} is the default implementation of the
+ * {@link ArgumentConverter} API.
  *
- * The {@code @DefaultArgumentConverter} is able to convert from strings to
- * a number of primitive (Byte, Short, Integer, Long, Float, and Double)
- * and date types.
+ * <p>The {@code DefaultArgumentConverter} is able to convert from strings to a
+ * number of primitive types and their corresponding wrapper types (Byte, Short,
+ * Integer, Long, Float, and Double) as well as date and time types from the
+ * {@code java.time} package.
  *
- * If the source and target types are identical the object is left unchanged.
+ * <p>If the source and target types are identical the source object will not
+ * be modified.
  *
- * @see org.junit.jupiter.params.converter.ArgumentConverter
  * @since 5.0
+ * @see org.junit.jupiter.params.converter.ArgumentConverter
  */
 @API(Internal)
 public class DefaultArgumentConverter extends SimpleArgumentConverter {
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/JavaTimeConversionPattern.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/JavaTimeConversionPattern.java
@@ -26,9 +26,9 @@
  * conversion pattern to be specified on a method parameter of a
  * {@link ParameterizedTest} method.
  *
+ * @since 5.0
  * @see org.junit.jupiter.params.ParameterizedTest
  * @see java.time.format.DateTimeFormatterBuilder#appendPattern(String)
- * @since 5.0
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.PARAMETER })
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/SimpleArgumentConverter.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/converter/SimpleArgumentConverter.java
@@ -16,11 +16,11 @@
 import org.junit.platform.commons.meta.API;
 
 /**
- * {@code @ArgumentConverter} is an abtract base class for {@code @ArgumentConverter}
+ * {@code SimpleArgumentConverter} is an abstract base class for {@link ArgumentConverter}
  * implementations.
  *
- * @see org.junit.jupiter.params.converter.ArgumentConverter
  * @since 5.0
+ * @see ArgumentConverter
  */
 @API(Experimental)
 public abstract class SimpleArgumentConverter implements ArgumentConverter {
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/Arguments.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/Arguments.java
@@ -18,13 +18,13 @@
  * {@code Arguments} is an abstraction that provides access to an array of
  * objects to be used for invoking a {@code @ParameterizedTest} method.
  *
- * A {@link java.util.stream.Stream} of such {@code Arguments} will
- * typically be accessed via {@linkplain ArgumentsProvider providers}.
+ * <p>A {@link java.util.stream.Stream} of such {@code Arguments} will
+ * typically be provided by an {@link ArgumentsProvider}.
  *
+ * @since 5.0
  * @see org.junit.jupiter.params.ParameterizedTest
  * @see org.junit.jupiter.params.provider.ArgumentsSource
  * @see org.junit.jupiter.params.provider.ArgumentsProvider
- * @since 5.0
  */
 @API(Experimental)
 public interface Arguments {
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/ArgumentsProvider.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/ArgumentsProvider.java
@@ -18,15 +18,17 @@
 import org.junit.platform.commons.meta.API;
 
 /**
- *  Implementations of {@code ArgumentsProvider} are responsible for providing a
- *  {@link java.util.stream.Stream} of {@code Arguments}.
- *  Such a stream will then be used for invoking a {@code @ParameterizedTest} method.
- *  {@code ArgumentsProvider}s are registered via {@code @ArgumentsSource} annotations.
+ * Implementations of {@code ArgumentsProvider} are responsible for providing a
+ * {@link Stream} of {@code Arguments}.
  *
+ * <p>Such a stream will then be used for invoking a {@code @ParameterizedTest} method.
+ *
+ * <p>{@code ArgumentsProvider}s are registered via {@code @ArgumentsSource} annotations.
+ *
+ * @since 5.0
  * @see org.junit.jupiter.params.ParameterizedTest
  * @see org.junit.jupiter.params.provider.ArgumentsSource
  * @see org.junit.jupiter.params.provider.Arguments
- * @since 5.0
  */
 @API(Experimental)
 public interface ArgumentsProvider {
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/ArgumentsSource.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/ArgumentsSource.java
@@ -26,8 +26,8 @@
  * that is used to register {@linkplain ArgumentsProvider providers} for the
  * annotated test class or test method.
  *
- * @see org.junit.jupiter.params.provider.ArgumentsProvider
  * @since 5.0
+ * @see org.junit.jupiter.params.provider.ArgumentsProvider
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/ArgumentsSources.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/ArgumentsSources.java
@@ -21,10 +21,15 @@
 import org.junit.platform.commons.meta.API;
 
 /**
- * {@code @ArgumentsSources}  is a simple container for one or more {@link ArgumentsSource} annotations.
+ * {@code @ArgumentsSources} is a simple container for one or more
+ * {@link ArgumentsSource} annotations.
+ *
+ * <p>Note, however, that use of the {@code @ArgumentsSources} container is completely
+ * optional since {@code @ArgumentsSource} is a {@linkplain java.lang.annotation.Repeatable
+ * repeatable} annotation.
  *
- * @see org.junit.jupiter.params.provider.ArgumentsSource
  * @since 5.0
+ * @see org.junit.jupiter.params.provider.ArgumentsSource
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvFileSource.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvFileSource.java
@@ -21,16 +21,16 @@
 import org.junit.platform.commons.meta.API;
 
 /**
- * {@code @CsvFileSource} is a special {@link ArgumentsSource} which reads files
- * with comma-separated values (CSV) from one or more classpath resources.
+ * {@code @CsvFileSource} is a special {@link ArgumentsSource} which is used to
+ * declare comma-separated values (CSV) files from one or more classpath resources.
  *
- * The contents of these resources are then provided as arguments to
+ * <p>The lines of these CSV files are then provided as arguments to
  * {@code @ParameterizedTest} methods using a {@code @CsvFileArgumentsProvider}.
  *
+ * @since 5.0
  * @see org.junit.jupiter.params.provider.ArgumentsSource
  * @see org.junit.jupiter.params.provider.CsvFileArgumentsProvider
  * @see org.junit.jupiter.params.ParameterizedTest
- * @since 5.0
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvSource.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvSource.java
@@ -22,15 +22,15 @@
 
 /**
  * {@code @CsvSource} is a special {@link ArgumentsSource} which reads
- * comma-separated values (CSV) from its {@code value} field.
+ * comma-separated values (CSV) from its {@link value} attribute.
  *
- * These values are then provided as arguments to {@code @ParameterizedTest}
+ * <p>These values are then provided as arguments to {@code @ParameterizedTest}
  * methods using a {@code @CsvArgumentsProvider}.
  *
+ * @since 5.0
  * @see org.junit.jupiter.params.provider.ArgumentsSource
  * @see org.junit.jupiter.params.provider.CsvArgumentsProvider
  * @see org.junit.jupiter.params.ParameterizedTest
- * @since 5.0
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/EnumSource.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/EnumSource.java
@@ -22,18 +22,18 @@
 
 /**
  * {@code @EnumSource} is a special {@link ArgumentsSource} which provides
- * access to the possible values of an {@code Enum}.
+ * access to the possible constants of specified {@linkplain #value Enum}.
  *
- * The contents of these resources are then provided as arguments to
- * {@code @ParameterizedTest} methods using an {@code @EnumArgumentsProvider}.
+ * <p>The enum constants are then provided as arguments to {@code @ParameterizedTest}
+ * methods using an {@code @EnumArgumentsProvider}.
  *
- * The available values can be restricted by listing the desired values
- * in the {@code names} field.
+ * <p>The set of enum constants can be restricted by listing the desired values
+ * via the {@link #names} attribute.
  *
+ * @since 5.0
  * @see org.junit.jupiter.params.provider.ArgumentsSource
  * @see org.junit.jupiter.params.provider.EnumArgumentsProvider
  * @see org.junit.jupiter.params.ParameterizedTest
- * @since 5.0
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
@@ -42,10 +42,19 @@
 @ArgumentsSource(EnumArgumentsProvider.class)
 public @interface EnumSource {
 
+	/**
+	 * The enum type that serves as the source of the enum constants.
+	 *
+	 * @see #names
+	 */
 	Class<? extends Enum<?>> value();
 
 	/**
-	 * @return names of enum constants to provide; if no name is given, all declared enum constants are provided.
+	 * The names of enum constants to provide.
+	 *
+	 * <p>If no names are specified, all declared enum constants will be provided.
+	 *
+	 * @see #value
 	 */
 	String[] names() default {};
 
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/MethodSource.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/MethodSource.java
@@ -25,13 +25,13 @@
  * access to the values returned by static methods of the class in which the
  * annotation is used.
  *
- * These values are then provided as arguments to {@code @ParameterizedTest}
+ * <p>These values are then provided as arguments to {@code @ParameterizedTest}
  * methods using a {@code @MethodArgumentsProvider}.
  *
+ * @since 5.0
  * @see org.junit.jupiter.params.provider.ArgumentsSource
  * @see org.junit.jupiter.params.provider.MethodArgumentsProvider
  * @see org.junit.jupiter.params.ParameterizedTest
- * @since 5.0
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/ObjectArrayArguments.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/ObjectArrayArguments.java
@@ -17,16 +17,16 @@
 /**
  * Concrete implementation of the {@code Arguments} abstraction.
  *
- * It provides access to an array of objects to be used for invoking a
+ * <p>It provides access to an array of objects to be used for invoking a
  * {@code @ParameterizedTest} method.
  *
- * A {@link java.util.stream.Stream} of such {@code Arguments} will
+ * <p>A {@link java.util.stream.Stream} of such {@code Arguments} will
  * typically be accessed via {@linkplain ArgumentsProvider providers}.
  *
+ * @since 5.0
  * @see org.junit.jupiter.params.ParameterizedTest
  * @see org.junit.jupiter.params.provider.ArgumentsSource
  * @see org.junit.jupiter.params.provider.ArgumentsProvider
- * @since 5.0
  */
 @API(Experimental)
 public class ObjectArrayArguments implements Arguments {
@@ -45,4 +45,5 @@ private ObjectArrayArguments(Object... arguments) {
 	public Object[] get() {
 		return arguments;
 	}
+
 }
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/ValueSource.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/ValueSource.java
@@ -23,15 +23,17 @@
 /**
  * {@code @ValueSource} is a special {@link ArgumentsSource} which provides
  * access to an array of literal values of certain primitive types.
- * These primitive types include String, int, long, and double.
  *
- * These values are then provided as arguments to {@code @ParameterizedTest}
+ * <p>Supported primitive types include {@link #strings}, {@link #ints},
+ * {@link #longs}, and {@link #doubles}.
+ *
+ * <p>These values are then provided as arguments to {@code @ParameterizedTest}
  * methods using a {@code @ValueArgumentsProvider}.
  *
+ * @since 5.0
  * @see org.junit.jupiter.params.provider.ArgumentsSource
  * @see org.junit.jupiter.params.provider.ValueArgumentsProvider
  * @see org.junit.jupiter.params.ParameterizedTest
- * @since 5.0
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/junit-jupiter-params/src/main/java/org/junit/jupiter/params/support/AnnotationConsumer.java b/junit-jupiter-params/src/main/java/org/junit/jupiter/params/support/AnnotationConsumer.java
@@ -21,8 +21,8 @@
  * {@code @AnnotationConsumer} is a {@code @FunctionalInterface} for consuming
  * {@code Annotation}s.
  *
- * It is typically implemented by implementations of {@code ArgumentsProvider}
- * signalling that they can {@code accept} a certain annotation.
+ * <p>It is typically implemented by implementations of {@code ArgumentsProvider}
+ * in order to signal that they can {@code accept} a certain annotation.
  *
  * @since 5.0
  */
