Improve Javadoc for @ClassTemplate, ParameterDeclarations, etc.

Closes #5165

Author: sbrannen

junit-jupiter-api/src/main/java/org/junit/jupiter/api/ClassTemplate.java

@@ -20,32 +20,25 @@
 import java.lang.annotation.Target;
 
 import org.apiguardian.api.API;
-import org.junit.jupiter.api.extension.AfterClassTemplateInvocationCallback;
-import org.junit.jupiter.api.extension.BeforeClassTemplateInvocationCallback;
-import org.junit.jupiter.api.extension.ClassTemplateInvocationContext;
-import org.junit.jupiter.api.extension.ClassTemplateInvocationContextProvider;
 import org.junit.platform.commons.annotation.Testable;
 
 /**
  * {@code @ClassTemplate} is used to signal that the annotated class is a
  * <em>class template</em>.
  *
  * <p>In contrast to regular test classes, a class template is not directly
- * a test class but rather a template for a set of test cases. As such, it is
+ * a test class but rather a template for a set of test classes. As such, it is
  * designed to be invoked multiple times depending on the number of {@linkplain
- * ClassTemplateInvocationContext invocation
- * contexts} returned by the registered {@linkplain
- * ClassTemplateInvocationContextProvider
- * providers}. Must be used together with at least one provider. Otherwise,
- * execution will fail.
+ * org.junit.jupiter.api.extension.ClassTemplateInvocationContext invocation contexts}
+ * returned by the registered {@linkplain
+ * org.junit.jupiter.api.extension.ClassTemplateInvocationContextProvider providers}.
+ * Must be used together with at least one provider. Otherwise, execution will fail.
  *
- * <p>Each invocation of a class template method behaves like the execution
- * of a regular test class with full support for the same lifecycle callbacks
- * and extensions.
+ * <p>Each invocation of a class template behaves like the execution of a regular
+ * test class with full support for the same lifecycle callbacks and extensions.
  *
- * <p>{@code @ClassTemplate} may be combined with {@link Nested @Nested} and
- * a class template may contain regular nested test classes or nested
- * class templates.
+ * <p>{@code @ClassTemplate} may be combined with {@link Nested @Nested}, and a
+ * class template may contain regular nested test classes or nested class templates.
  *
  * <p>{@code @ClassTemplate} may also be used as a meta-annotation in order
  * to create a custom <em>composed annotation</em> that inherits the semantics
@@ -56,11 +49,11 @@
  * <p>This annotation is inherited by subclasses.
  *
  * @since 5.13
- * @see TestTemplate
- * @see ClassTemplateInvocationContext
- * @see ClassTemplateInvocationContextProvider
- * @see BeforeClassTemplateInvocationCallback
- * @see AfterClassTemplateInvocationCallback
+ * @see TestTemplate @TestTemplate
+ * @see org.junit.jupiter.api.extension.ClassTemplateInvocationContext ClassTemplateInvocationContext
+ * @see org.junit.jupiter.api.extension.ClassTemplateInvocationContextProvider ClassTemplateInvocationContextProvider
+ * @see org.junit.jupiter.api.extension.BeforeClassTemplateInvocationCallback BeforeClassTemplateInvocationCallback
+ * @see org.junit.jupiter.api.extension.AfterClassTemplateInvocationCallback AfterClassTemplateInvocationCallback
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/AfterClassTemplateInvocationCallback.java

@@ -18,7 +18,7 @@
 /**
  * {@code AfterClassTemplateInvocationCallback} defines the API for
  * {@link Extension Extensions} that wish to provide additional behavior
- * <strong>once</strong> before each invocation of a
+ * <strong>once</strong> after each invocation of a
  * {@link ClassTemplate @ClassTemplate}.
  *
  * <p>Concrete implementations often implement
@@ -34,7 +34,7 @@
  * <p>JUnit Jupiter guarantees <em>wrapping behavior</em> for multiple
  * registered extensions that implement lifecycle callbacks such as
  * {@link BeforeAllCallback}, {@link AfterAllCallback},
- * {@link AfterClassTemplateInvocationCallback},
+ * {@link BeforeClassTemplateInvocationCallback},
  * {@link AfterClassTemplateInvocationCallback}, {@link BeforeEachCallback},
  * {@link AfterEachCallback}, {@link BeforeTestExecutionCallback}, and
  * {@link AfterTestExecutionCallback}.
@@ -64,7 +64,7 @@
 public interface AfterClassTemplateInvocationCallback extends Extension {
 
 	/**
-	 * Callback that is invoked <em>after</em> each invocation of a container
+	 * Callback that is invoked <em>after</em> each invocation of a class
 	 * template.
 	 *
 	 * @param context the current extension context; never {@code null}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/BeforeClassTemplateInvocationCallback.java

@@ -64,7 +64,7 @@
 public interface BeforeClassTemplateInvocationCallback extends Extension {
 
 	/**
-	 * Callback that is invoked <em>before</em> each invocation of a container
+	 * Callback that is invoked <em>before</em> each invocation of a class
 	 * template.
 	 *
 	 * @param context the current extension context; never {@code null}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ClassTemplateInvocationContext.java

@@ -22,8 +22,7 @@
  * {@code ClassTemplateInvocationContext} represents the <em>context</em> of
  * a single invocation of a {@link ClassTemplate @ClassTemplate}.
  *
- * <p>Each context is provided by a
- * {@link ClassTemplateInvocationContextProvider}.
+ * <p>Each context is provided by a {@link ClassTemplateInvocationContextProvider}.
  *
  * @since 5.13
  * @see ClassTemplate
@@ -36,7 +35,7 @@ public interface ClassTemplateInvocationContext {
 	 * Get the display name for this invocation.
 	 *
 	 * <p>The supplied {@code invocationIndex} is incremented by the framework
-	 * with each container invocation. Thus, in the case of multiple active
+	 * with each class template invocation. Thus, in the case of multiple active
 	 * {@linkplain ClassTemplateInvocationContextProvider providers}, only the
 	 * first active provider receives indices starting with {@code 1}.
 	 *
@@ -51,16 +50,16 @@ default String getDisplayName(int invocationIndex) {
 	}
 
 	/**
-	 * Get the additional {@linkplain Extension extensions} for this invocation.
+	 * Get additional {@linkplain Extension extensions} for this invocation.
 	 *
 	 * <p>The extensions provided by this method will only be used for this
 	 * invocation of the class template. Thus, it does not make sense to return
-	 * an extension that acts solely on the container level (e.g.
-	 * {@link BeforeAllCallback}).
+	 * an extension that needs to perform some action at the container level,
+	 * such as an implementation of {@link BeforeAllCallback}.
 	 *
 	 * <p>The default implementation returns an empty list.
 	 *
-	 * @return the additional extensions for this invocation; never {@code null}
+	 * @return additional extensions for this invocation; never {@code null}
 	 * or containing {@code null} elements, but potentially empty
 	 */
 	default List<Extension> getAdditionalExtensions() {
@@ -74,7 +73,7 @@ default List<Extension> getAdditionalExtensions() {
 	 * {@link ExtensionContext.Store Store} to benefit from its cleanup support
 	 * or for retrieval by other extensions.
 	 *
-	 * @param context The invocation-level extension context.
+	 * @param context the invocation-level extension context
 	 */
 	default void prepareInvocation(ExtensionContext context) {
 	}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ClassTemplateInvocationContextProvider.java

@@ -22,37 +22,34 @@
  * {@link Extension Extensions} that wish to provide one or multiple contexts
  * for the invocation of a {@link ClassTemplate @ClassTemplate}.
  *
- * <p>This extension point makes it possible to execute a class template in
+ * <p>This extension API makes it possible to execute a class template in
  * different contexts &mdash; for example, with different parameters, by
  * preparing the test class instance differently, or multiple times without
  * modifying the context.
  *
- * <p>This interface defines two main methods:
- * {@link #supportsClassTemplate} and
+ * <p>This interface defines two main methods: {@link #supportsClassTemplate} and
  * {@link #provideClassTemplateInvocationContexts}. The former is called by the
- * framework to determine whether this extension wants to act on a container
+ * framework to determine whether this extension wants to act on a class
  * template that is about to be executed. If so, the latter is called and must
  * return a {@link Stream} of {@link ClassTemplateInvocationContext} instances.
  * Otherwise, this provider is ignored for the execution of the current class
  * template.
  *
- * <p>A provider that has returned {@code true} from its
- * {@link #supportsClassTemplate} method is called <em>active</em>. When
- * multiple providers are active for a class template, the
- * {@code Streams} returned by their
+ * <p>A provider that has returned {@code true} from its {@link #supportsClassTemplate}
+ * method is called <em>active</em>. When multiple providers are active for a class
+ * template, the {@code Streams} returned by their
  * {@link #provideClassTemplateInvocationContexts} methods will be chained, and
  * the class template method will be invoked using the contexts of all active
  * providers.
  *
  * <p>An active provider may return zero invocation contexts from its
  * {@link #provideClassTemplateInvocationContexts} method if it overrides
- * {@link #mayReturnZeroClassTemplateInvocationContexts} to return
- * {@code true}.
+ * {@link #mayReturnZeroClassTemplateInvocationContexts} to return {@code true}.
  *
  * <h2>Constructor Requirements</h2>
  *
- * <p>Consult the documentation in {@link Extension} for details on
- * constructor requirements.
+ * <p>Consult the documentation in {@link Extension} for details on constructor
+ * requirements.
  *
  * @since 5.13
  * @see ClassTemplate
@@ -90,8 +87,8 @@ public interface ClassTemplateInvocationContextProvider extends Extension {
 	 * invoked; never {@code null}
 	 * @return a {@code Stream} of {@code ClassTemplateInvocationContext}
 	 * instances for the invocation of the class template; never {@code null}
-	 * @throws TemplateInvocationValidationException if a validation fails when
-	 * while providing or closing the {@link java.util.stream.Stream}.
+	 * @throws TemplateInvocationValidationException if validation fails while
+	 * providing or closing the {@link Stream}
 	 * @see #supportsClassTemplate
 	 * @see ExtensionContext
 	 */

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestTemplateInvocationContext.java

@@ -36,7 +36,7 @@ public interface TestTemplateInvocationContext {
 	 * Get the display name for this invocation.
 	 *
 	 * <p>The supplied {@code invocationIndex} is incremented by the framework
-	 * with each test invocation. Thus, in the case of multiple active
+	 * with each test template invocation. Thus, in the case of multiple active
 	 * {@linkplain TestTemplateInvocationContextProvider providers}, only the
 	 * first active provider receives indices starting with {@code 1}.
 	 *
@@ -51,16 +51,16 @@ default String getDisplayName(int invocationIndex) {
 	}
 
 	/**
-	 * Get the additional {@linkplain Extension extensions} for this invocation.
+	 * Get additional {@linkplain Extension extensions} for this invocation.
 	 *
 	 * <p>The extensions provided by this method will only be used for this
 	 * invocation of the test template. Thus, it does not make sense to return
-	 * an extension that acts solely on the container level (e.g.
-	 * {@link BeforeAllCallback}).
+	 * an extension that needs to perform some action at the container level,
+	 * such as an implementation of {@link BeforeAllCallback}.
 	 *
 	 * <p>The default implementation returns an empty list.
 	 *
-	 * @return the additional extensions for this invocation; never {@code null}
+	 * @return additional extensions for this invocation; never {@code null}
 	 * or containing {@code null} elements, but potentially empty
 	 */
 	default List<Extension> getAdditionalExtensions() {
@@ -74,7 +74,7 @@ default List<Extension> getAdditionalExtensions() {
 	 * {@link ExtensionContext.Store Store} to benefit from its cleanup support
 	 * or for retrieval by other extensions.
 	 *
-	 * @param context The invocation-level extension context.
+	 * @param context the invocation-level extension context
 	 * @since 5.13
 	 */
 	@API(status = EXPERIMENTAL, since = "6.0")

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/TestTemplateInvocationContextProvider.java

@@ -23,7 +23,7 @@
  * for the invocation of a
  * {@link org.junit.jupiter.api.TestTemplate @TestTemplate} method.
  *
- * <p>This extension point makes it possible to execute a test template in
+ * <p>This extension API makes it possible to execute a test template in
  * different contexts &mdash; for example, with different parameters, by
  * preparing the test class instance differently, or multiple times without
  * modifying the context.
@@ -48,8 +48,8 @@
  *
  * <h2>Constructor Requirements</h2>
  *
- * <p>Consult the documentation in {@link Extension} for details on
- * constructor requirements.
+ * <p>Consult the documentation in {@link Extension} for details on constructor
+ * requirements.
  *
  * @since 5.0
  * @see org.junit.jupiter.api.TestTemplate
@@ -86,8 +86,8 @@ public interface TestTemplateInvocationContextProvider extends Extension {
 	 * to be invoked; never {@code null}
 	 * @return a {@code Stream} of {@code TestTemplateInvocationContext}
 	 * instances for the invocation of the test template method; never {@code null}
-	 * @throws TemplateInvocationValidationException if a validation fails when
-	 * while providing or closing the {@link java.util.stream.Stream}.
+	 * @throws TemplateInvocationValidationException if validation fails while
+	 * providing or closing the {@link Stream}
 	 * @see #supportsTestTemplate
 	 * @see ExtensionContext
 	 */

junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterInfo.java

@@ -77,7 +77,7 @@ public interface ParameterInfo {
 	ParameterDeclarations getDeclarations();
 
 	/**
-	 * {@return the accessor to the arguments of the current invocation}
+	 * {@return an accessor for the arguments of the current invocation}
 	 */
 	ArgumentsAccessor getArguments();
 

junit-jupiter-params/src/main/java/org/junit/jupiter/params/aggregator/ArgumentsAccessor.java

@@ -21,17 +21,18 @@
  * {@code ArgumentsAccessor} defines the public API for accessing arguments provided
  * by an {@link org.junit.jupiter.params.provider.ArgumentsProvider ArgumentsProvider}
  * for a single invocation of a
- * {@link org.junit.jupiter.params.ParameterizedTest @ParameterizedTest} method.
+ * {@link org.junit.jupiter.params.ParameterizedClass @ParameterizedClass} or
+ * {@link org.junit.jupiter.params.ParameterizedTest @ParameterizedTest}.
  *
  * <p>Specifically, an {@code ArgumentsAccessor} <em>aggregates</em> a set of
- * arguments for a given invocation of a parameterized test and provides convenience
- * methods for accessing those arguments in a type-safe manner with support for
- * automatic type conversion.
+ * arguments for a given invocation of a parameterized class or parameterized
+ * test and provides convenience methods for accessing those arguments in a
+ * type-safe manner with support for automatic type conversion.
  *
  * <p>An instance of {@code ArgumentsAccessor} will be automatically supplied
- * for any parameter of type {@code ArgumentsAccessor} in a parameterized test.
- * In addition, {@link ArgumentsAggregator} implementations are given access to
- * an {@code ArgumentsAccessor}.
+ * for any parameter of type {@code ArgumentsAccessor} in a parameterized class
+ * or parameterized test. In addition, {@link ArgumentsAggregator} implementations
+ * are given access to an {@code ArgumentsAccessor}.
  *
  * <p>This interface is not intended to be implemented by clients.
  *
@@ -201,7 +202,8 @@ public interface ArgumentsAccessor {
 	List<@Nullable Object> toList();
 
 	/**
-	 * Get the index of the current test invocation.
+	 * Get the index of the current invocation.
 	 */
 	int getInvocationIndex();
+
 }

junit-jupiter-params/src/main/java/org/junit/jupiter/params/support/ParameterDeclarations.java

@@ -21,18 +21,18 @@
 
 /**
  * {@code ParameterDeclarations} encapsulates the combined <em>declarations</em>
- * of all <em>indexed</em> {@code @ParameterizedClass} or
- * {@code @ParameterizedTest} parameters.
+ * of all <em>indexed</em> parameters for a {@code @ParameterizedClass} or
+ * {@code @ParameterizedTest}.
  *
  * <p>For a {@code @ParameterizedTest}, the parameter declarations are derived
  * from the method signature. For a {@code @ParameterizedClass}, they may be
  * derived from the constructor or
- * {@link java.lang.reflect.Parameter @Parameter}-annotated fields.
+ * {@link org.junit.jupiter.params.Parameter @Parameter}-annotated fields.
  *
- * <p>Aggregators, that is parameters of type
- * {@link ArgumentsAccessor ArgumentsAccessor} or parameters annotated with
- * {@link org.junit.jupiter.params.aggregator.AggregateWith @AggregateWith}, are
- * <em>not</em> indexed and thus not included in the list of parameter
+ * <p>Aggregators &mdash; parameters of type {@link ArgumentsAccessor ArgumentsAccessor}
+ * or parameters annotated with
+ * {@link org.junit.jupiter.params.aggregator.AggregateWith @AggregateWith} &mdash;
+ * are <em>not</em> indexed and thus not included in the list of parameter
  * declarations.
  *
  * @since 5.13
@@ -44,20 +44,20 @@
 public interface ParameterDeclarations {
 
 	/**
-	 * {@return all <em>indexed</em> parameter declarations; never {@code null},
-	 * sorted by index}
+	 * {@return all <em>indexed</em> parameter declarations, sorted by index;
+	 * never {@code null}, but potentially empty}
 	 */
 	List<ParameterDeclaration> getAll();
 
 	/**
 	 * {@return the first <em>indexed</em> parameter declaration, if available;
-	 * never {@code null}}
+	 * never {@code null}, but potentially empty}
 	 */
 	Optional<ParameterDeclaration> getFirst();
 
 	/**
 	 * {@return the <em>indexed</em> parameter declaration for the supplied
-	 * index, if available; never {@code null}}
+	 * index, if available; never {@code null}, but potentially empty}
 	 */
 	Optional<ParameterDeclaration> get(int parameterIndex);