Improve documentation for TestInstantiationAwareExtension

This commit improves the documentation for TestInstantiationAwareExtension
and raises awareness of semantic differences by introducing class-level
notes the Javadoc for all affected extension APIs.

Closes #5107

Author: sbrannen

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

@@ -45,6 +45,16 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h2>{@code ExtensionContext} Scope</h2>
+ *
+ * <p>As of JUnit Jupiter 5.12, this API participates in the
+ * {@link TestInstantiationAwareExtension} contract. Implementations of this API
+ * may therefore choose to override
+ * {@link TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
+ * getTestInstantiationExtensionContextScope(ExtensionContext)}. See
+ * {@link #interceptTestClassConstructor(Invocation, ReflectiveInvocationContext, ExtensionContext)}
+ * for details.
+ *
  * @since 5.5
  * @see Invocation
  * @see ReflectiveInvocationContext

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

@@ -47,6 +47,15 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h2>{@code ExtensionContext} Scope</h2>
+ *
+ * <p>As of JUnit Jupiter 5.12, this API participates in the
+ * {@link TestInstantiationAwareExtension} contract. Implementations of this API
+ * may therefore choose to override
+ * {@link TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
+ * getTestInstantiationExtensionContextScope(ExtensionContext)} to require a
+ * test-method scoped {@code ExtensionContext}.
+ *
  * @since 5.0
  * @see #supportsParameter(ParameterContext, ExtensionContext)
  * @see #resolveParameter(ParameterContext, ExtensionContext)

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

@@ -43,6 +43,17 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h2>{@code ExtensionContext} Scope</h2>
+ *
+ * <p>As of JUnit Jupiter 5.12, this API participates in the
+ * {@link TestInstantiationAwareExtension} contract. Implementations of this API
+ * may therefore choose to override
+ * {@link TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
+ * getTestInstantiationExtensionContextScope(ExtensionContext)} to require a
+ * test-method scoped {@code ExtensionContext}. See
+ * {@link #createTestInstance(TestInstanceFactoryContext, ExtensionContext)} for
+ * further details.
+ *
  * @since 5.3
  * @see #createTestInstance(TestInstanceFactoryContext, ExtensionContext)
  * @see TestInstanceFactoryContext

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

@@ -33,6 +33,16 @@
  * <p>Consult the documentation in {@link Extension} for details on
  * constructor requirements.
  *
+ * <h2>{@code ExtensionContext} Scope</h2>
+ *
+ * <p>As of JUnit Jupiter 5.12, this API participates in the
+ * {@link TestInstantiationAwareExtension} contract. Implementations of this API
+ * may therefore choose to override
+ * {@link TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
+ * getTestInstantiationExtensionContextScope(ExtensionContext)} to require a
+ * test-method scoped {@code ExtensionContext}. See
+ * {@link #postProcessTestInstance(Object, ExtensionContext)} for further details.
+ *
  * @since 5.0
  * @see #postProcessTestInstance(Object, ExtensionContext)
  * @see TestInstancePreDestroyCallback

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

@@ -38,6 +38,17 @@
  * <p>Consult the documentation in {@link Extension} for details on constructor
  * requirements.
  *
+ * <h2>{@code ExtensionContext} Scope</h2>
+ *
+ * <p>As of JUnit Jupiter 5.12, this API participates in the
+ * {@link TestInstantiationAwareExtension} contract. Implementations of this API
+ * may therefore choose to override
+ * {@link TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
+ * getTestInstantiationExtensionContextScope(ExtensionContext)} to require a
+ * test-method scoped {@code ExtensionContext}. See
+ * {@link #preConstructTestInstance(TestInstanceFactoryContext, ExtensionContext)}
+ * for further details.
+ *
  * @since 5.9
  * @see TestInstancePreDestroyCallback
  * @see TestInstanceFactory

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

@@ -14,79 +14,119 @@
 import static org.apiguardian.api.API.Status.MAINTAINED;
 
 import org.apiguardian.api.API;
-import org.junit.jupiter.api.TestInstance;
-import org.junit.jupiter.api.extension.ExtensionContext.Store;
 
 /**
- * Interface for {@link Extension Extensions} that are aware and can influence
- * the instantiation of test instances.
+ * {@code TestInstantiationAwareExtension} defines the API for {@link Extension
+ * Extensions} that are aware of or influence the instantiation of test classes.
  *
- * <p>This interface is not indented to be implemented directly. Instead, extend
- * one of its sub-interfaces.
+ * <p>This interface is not intended to be implemented directly. Instead, extensions
+ * should implement one of the sub-interfaces listed below.
+ *
+ * <ul>
+ * <li>{@link InvocationInterceptor}</li>
+ * <li>{@link ParameterResolver}</li>
+ * <li>{@link TestInstancePreConstructCallback}</li>
+ * <li>{@link TestInstancePostProcessor}</li>
+ * <li>{@link TestInstanceFactory}</li>
+ * </ul>
+ *
+ * <p>See {@link #getTestInstantiationExtensionContextScope(ExtensionContext)} for
+ * further details.
  *
  * @since 5.12
- * @see InvocationInterceptor#interceptTestClassConstructor
- * @see ParameterResolver
- * @see TestInstancePreConstructCallback
- * @see TestInstancePostProcessor
- * @see TestInstanceFactory
  */
 @API(status = MAINTAINED, since = "5.13.3")
 public interface TestInstantiationAwareExtension extends Extension {
 
 	/**
-	 * Whether this extension should receive a test-scoped
-	 * {@link ExtensionContext} during the instantiation of test instances.
+	 * Determine whether this extension should receive a test-method scoped
+	 * {@link ExtensionContext} during the instantiation of test classes or
+	 * processing of test instances.
 	 *
-	 * <p>If an extension returns
-	 * {@link ExtensionContextScope#TEST_METHOD TEST_METHOD} from this method,
-	 * the following extension methods will be called with a test-scoped
-	 * {@link ExtensionContext} instead of a class-scoped one, unless the
-	 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used:
+	 * <p>If an extension returns {@link ExtensionContextScope#TEST_METHOD TEST_METHOD}
+	 * from this method, methods defined in the following extension APIs will be
+	 * called with a test-method scoped {@code ExtensionContext} instead of a
+	 * test-class scoped context. Note, however, that a test-class scoped context
+	 * will always be supplied if the
+	 * {@link org.junit.jupiter.api.TestInstance.Lifecycle#PER_CLASS PER_CLASS}
+	 * test instance lifecycle is used.
 	 *
 	 * <ul>
-	 * <li>{@link InvocationInterceptor#interceptTestClassConstructor}</li>
-	 * <li>{@link ParameterResolver} when resolving constructor parameters</li>
+	 * <li>{@link InvocationInterceptor}: only the
+	 * {@link InvocationInterceptor#interceptTestClassConstructor
+	 * interceptTestClassConstructor(...)} method</li>
+	 * <li>{@link ParameterResolver}: only when resolving constructor parameters</li>
 	 * <li>{@link TestInstancePreConstructCallback}</li>
 	 * <li>{@link TestInstancePostProcessor}</li>
 	 * <li>{@link TestInstanceFactory}</li>
 	 * </ul>
 	 *
-	 * <p>In such cases, implementations of these extension callbacks can
-	 * observe the following differences:
+	 * <p>When a test-method scoped {@code ExtensionContext} is supplied, implementations
+	 * of the above extension APIs will observe the following differences.
 	 *
 	 * <ul>
-	 * <li>{@link ExtensionContext#getElement() getElement()} may refer to the
-	 * test method and {@link ExtensionContext#getTestClass() getTestClass()}
-	 * may refer to a nested test class.
-	 * Use {@link TestInstanceFactoryContext#getTestClass()} to get the class
-	 * under construction.</li>
-	 * <li>{@link ExtensionContext#getTestMethod() getTestMethod()} is no longer
-	 * empty, unless the {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS}
-	 * lifecycle is used.</li>
-	 * <li>If the callback adds a new {@link Store.CloseableResource} or
-	 * {@link AutoCloseable} to the {@link Store Store} (unless the
-	 * {@code junit.jupiter.extensions.store.close.autocloseable.enabled}
-	 * configuration parameter is set to {@code false}), then
-	 * the resource is closed just after the instance is destroyed.</li>
-	 * <li>The callbacks can now access data previously stored by
-	 * {@link TestTemplateInvocationContext}, unless the
-	 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used.</li>
+	 *   <li>
+	 *     {@link ExtensionContext#getElement() getElement()} may refer to the
+	 *     test method.
+	 *   </li>
+	 *   <li>
+	 *     {@link ExtensionContext#getTestClass() getTestClass()} may refer to a
+	 *     nested test class.
+	 *     <ul>
+	 *       <li>
+	 *         For {@link TestInstancePostProcessor}, use {@code testInstance.getClass()}
+	 *         to get the test class associated with the supplied instance.
+	 *       </li>
+	 *       <li>
+	 *         For {@link TestInstanceFactory} and {@link TestInstancePreConstructCallback},
+	 *         use {@link TestInstanceFactoryContext#getTestClass()} to get the
+	 *         class under construction.
+	 *       </li>
+	 *       <li>
+	 *         For {@link ParameterResolver}, when resolving a parameter for a
+	 *         constructor, ensure that the
+	 *         {@link ParameterContext#getDeclaringExecutable() Executable} is a
+	 *         {@link java.lang.reflect.Constructor Constructor}, and then use
+	 *         {@code constructor.getDeclaringClass()} to get the test class
+	 *         associated with the constructor.
+	 *       </li>
+	 *     </ul>
+	 *   </li>
+	 *   <li>
+	 *     {@link ExtensionContext#getTestMethod() getTestMethod()} is no longer
+	 *     empty, unless the
+	 *     {@link org.junit.jupiter.api.TestInstance.Lifecycle#PER_CLASS PER_CLASS}
+	 *     test instance lifecycle is used.
+	 *   </li>
+	 *   <li>
+	 *     If the extension adds a {@link ExtensionContext.Store.CloseableResource
+	 *     CloseableResource} or {@link AutoCloseable} to the
+	 *     {@link ExtensionContext.Store Store} (unless the
+	 *     {@code junit.jupiter.extensions.store.close.autocloseable.enabled}
+	 *     configuration parameter is set to {@code false}), then the resource will
+	 *     be closed just after the instance is destroyed.
+	 *   </li>
+	 *   <li>
+	 *     Extensions can now access data previously stored by a
+	 *     {@link TestTemplateInvocationContext}, unless the
+	 *     {@link org.junit.jupiter.api.TestInstance.Lifecycle#PER_CLASS PER_CLASS}
+	 *     test instance lifecycle is used.
+	 *   </li>
 	 * </ul>
 	 *
 	 * <p><strong>Note</strong>: The behavior which is enabled by returning
 	 * {@link ExtensionContextScope#TEST_METHOD TEST_METHOD} from this method
 	 * will become the default in future versions of JUnit. To ensure forward
-	 * compatibility, extension implementors are therefore advised to opt in,
-	 * even if they don't require the new functionality.
+	 * compatibility, extension authors are therefore advised to opt into this
+	 * feature, even if they do not require the new functionality.
 	 *
-	 * @implNote There are no guarantees about how often this method is called.
-	 *           Therefore, implementations should be idempotent and avoid side
-	 *           effects. They may, however, cache the result for performance in
-	 *           the {@link Store Store} of the supplied
-	 *           {@link ExtensionContext}, if necessary.
+	 * @implNote There are no guarantees about how often this method will be called.
+	 * Therefore, implementations should be idempotent and avoid side effects.
+	 * If computation of the return value is costly, implementations may wish to
+	 * cache the result in the {@link ExtensionContext.Store Store} of the supplied
+	 * {@code ExtensionContext}.
 	 * @param rootContext the root extension context to allow inspection of
-	 *                    configuration parameters; never {@code null}
+	 * configuration parameters; never {@code null}
 	 * @since 5.12
 	 */
 	@API(status = MAINTAINED, since = "5.13.3")
@@ -96,25 +136,25 @@ default ExtensionContextScope getTestInstantiationExtensionContextScope(Extensio
 
 	/**
 	 * {@code ExtensionContextScope} is used to define the scope of the
-	 * {@link ExtensionContext} passed to an extension during the instantiation
-	 * of test instances.
+	 * {@link ExtensionContext} supplied to an extension during the instantiation
+	 * of test classes or processing of test instances.
 	 *
 	 * @since 5.12
-	 * @see TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope
+	 * @see TestInstantiationAwareExtension#getTestInstantiationExtensionContextScope(ExtensionContext)
 	 */
 	@API(status = MAINTAINED, since = "5.13.3")
 	enum ExtensionContextScope {
 
 		/**
-		 * The extension should receive an {@link ExtensionContext} scoped to
-		 * in the <em>default</em> scope.
+		 * The extension should receive an {@link ExtensionContext} for the
+		 * the <em>default</em> scope.
 		 *
 		 * <p>The default scope is determined by the configuration parameter
 		 * {@link #DEFAULT_SCOPE_PROPERTY_NAME}. If not specified, extensions
 		 * will receive an {@link ExtensionContext} scoped to the test class.
 		 *
 		 * @deprecated This behavior will be removed from future versions of
-		 * JUnit and {@link #TEST_METHOD} will become the default.
+		 * JUnit, and {@link #TEST_METHOD} will become the default.
 		 *
 		 * @see #DEFAULT_SCOPE_PROPERTY_NAME
 		 */
@@ -124,8 +164,12 @@ enum ExtensionContextScope {
 
 		/**
 		 * The extension should receive an {@link ExtensionContext} scoped to
-		 * the test method, unless the
-		 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used.
+		 * the test method.
+		 *
+		 * <p>Note, however, that a test-class scoped context will always be
+		 * supplied if the
+		 * {@link org.junit.jupiter.api.TestInstance.Lifecycle#PER_CLASS PER_CLASS}
+		 * test instance lifecycle is used.
 		 */
 		TEST_METHOD;
 
@@ -140,6 +184,7 @@ enum ExtensionContextScope {
 		 * @see #DEFAULT
 		 */
 		public static final String DEFAULT_SCOPE_PROPERTY_NAME = "junit.jupiter.extensions.testinstantiation.extensioncontextscope.default";
+
 	}
 
 }