Document inheritance support - part 2 (#5765)

Signed-off-by: Swati Chauhan <swati.chauhan814@gmail.com>

Author: swatichauhan814

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

@@ -44,8 +44,14 @@
  * <p>Display names are typically used for test reporting in IDEs and build
  * tools and may contain spaces, special characters, and even emoji.
  *
+ * <h2>Extensibility</h2>
+ *
+ * <p>This interface is designed to be implemented by clients.
+ *
  * <p>Concrete implementations must have a <em>default constructor</em>.
  *
+ * <h2>Configuration</h2>
+ *
  * <p>A {@link DisplayNameGenerator} can be configured <em>globally</em> for the
  * entire test suite via the {@value #DEFAULT_GENERATOR_PROPERTY_NAME}
  * configuration parameter (see the User Guide for details) or <em>locally</em>

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

@@ -22,6 +22,11 @@
  * Thrown if an error is encountered regarding the configuration of an
  * extension.
  *
+ * <h2>Extensibility</h2>
+ *
+ * <p>Although it is technically possible to extend this class, extension is
+ * strongly discouraged.
+ *
  * @since 5.0
  */
 @API(status = STABLE, since = "5.0")

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

@@ -24,6 +24,11 @@
  * Thrown if an error is encountered regarding the use of an
  * {@link ExtensionContext} or {@link Store}.
  *
+ * <h2>Extensibility</h2>
+ *
+ * <p>Although it is technically possible to extend this class, extension is
+ * strongly discouraged.
+ *
  * @since 5.0
  */
 @API(status = STABLE, since = "5.0")

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

@@ -22,6 +22,11 @@
  * Thrown if an error is encountered in the configuration or execution of a
  * {@link ParameterResolver}.
  *
+ * <h2>Extensibility</h2>
+ *
+ * <p>Although it is technically possible to extend this class, extension is
+ * strongly discouraged.
+ *
  * @since 5.0
  * @see ParameterResolver
  */

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

@@ -44,6 +44,10 @@
  * often they are called. Since instances may potentially be cached and called
  * from different threads, they should be thread-safe.
  *
+ * <h2>Extensibility</h2>
+ *
+ * <p>This interface is designed to be implemented by clients.
+ *
  * @since 5.2
  * @see AggregateWith
  * @see ArgumentsAccessor

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

@@ -23,6 +23,10 @@
  * {@link ArgumentsAggregator} implementations that do not need to distinguish
  * between fields and method/constructor parameters.
  *
+ * <h2>Extensibility</h2>
+ *
+ * <p>This class is designed for extension.
+ *
  * @since 5.0
  * @see ArgumentsAggregator
  */
@@ -32,12 +36,18 @@ public abstract class SimpleArgumentsAggregator implements ArgumentsAggregator {
 	public SimpleArgumentsAggregator() {
 	}
 
+	/**
+	 * By default, this method delegates to {@link #aggregateArguments(ArgumentsAccessor, Class, AnnotatedElementContext, int)}.
+	 */
 	@Override
 	public @Nullable Object aggregateArguments(ArgumentsAccessor accessor, ParameterContext context)
 			throws ArgumentsAggregationException {
 		return aggregateArguments(accessor, context.getParameter().getType(), context, context.getIndex());
 	}
 
+	/**
+	 * By default, this method delegates to {@link #aggregateArguments(ArgumentsAccessor, Class, AnnotatedElementContext, int)}.
+	 */
 	@Override
 	public @Nullable Object aggregateArguments(ArgumentsAccessor accessor, FieldContext context)
 			throws ArgumentsAggregationException {

junit-jupiter-params/src/main/java/org/junit/jupiter/params/provider/CsvParsingException.java

@@ -20,6 +20,11 @@
 /**
  * Thrown if an error is encountered while parsing CSV input.
  *
+ * <h2>Extensibility</h2>
+ *
+ * <p>Although it is technically possible to extend this class, extension is
+ * strongly discouraged.
+ *
  * @since 5.3
  * @see CsvSource
  * @see CsvFileSource

junit-platform-engine/src/main/java/org/junit/platform/engine/support/hierarchical/ExclusiveResource.java

@@ -27,6 +27,11 @@
  * An exclusive resource identified by a key with a lock mode that is used to
  * synchronize access to shared resources when executing nodes in parallel.
  *
+ * <h2>Extensibility</h2>
+ *
+ * <p>Although it is technically possible to extend this class, extension is
+ * strongly discouraged.
+ *
  * @since 1.3
  * @see Node#getExecutionMode()
  */

junit-platform-engine/src/main/java/org/junit/platform/engine/support/hierarchical/HierarchicalTestEngine.java

@@ -23,6 +23,10 @@
  * Abstract base class for all {@link TestEngine} implementations that wish
  * to organize test suites hierarchically based on the {@link Node} abstraction.
  *
+ * <h2>Extensibility</h2>
+ *
+ * <p>This class is designed for extension by test engine implementations.
+ *
  * @param <C> the type of {@code EngineExecutionContext} used by this engine
  * @since 1.0
  * @see Node
@@ -38,7 +42,11 @@ public HierarchicalTestEngine() {
 	 * service}; create an initial {@linkplain #createExecutionContext execution
 	 * context}; execute the behavior of all {@linkplain Node nodes} in the
 	 * hierarchy starting with the supplied {@code request}'s
-	 * {@linkplain ExecutionRequest#getRootTestDescriptor() root} and notify
+	 * {@linkplain ExecutionRequest#getRootTestDescriptor() root}, collecting
+	 * every thrown throwable using the
+	 * {@linkplain org.junit.platform.engine.support.hierarchical.ThrowableCollector
+	 * throwable collector} returned by
+	 * {@linkplain #createThrowableCollectorFactory(ExecutionRequest)}; and notify
 	 * its {@linkplain ExecutionRequest#getEngineExecutionListener() execution
 	 * listener} of test execution events.
 	 *
@@ -48,6 +56,7 @@ public HierarchicalTestEngine() {
 	 * @see Node
 	 * @see #createExecutorService
 	 * @see #createExecutionContext
+	 * @see #createThrowableCollectorFactory
 	 */
 	@Override
 	public final void execute(ExecutionRequest request) {

junit-platform-launcher/src/main/java/org/junit/platform/launcher/listeners/SummaryGeneratingListener.java

@@ -29,6 +29,11 @@
  * Simple {@link TestExecutionListener} that generates a
  * {@linkplain TestExecutionSummary summary} of the test execution.
  *
+ * <h2>Extensibility</h2>
+ *
+ * <p>Although it is technically possible to extend this class, extension is
+ * strongly discouraged.
+ *
  * @since 1.0
  * @see #getSummary()
  */