Fully document that @⁠TempDir can be used on constructor parameters

This commit is a followup to #4060.

Closes: #4285

Author: sbrannen

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -47,7 +47,7 @@ in the `junit-jupiter-api` module.
 | `@Disabled`              | Used to <<writing-tests-disabling,disable>> a test class or test method; analogous to JUnit 4's `@Ignore`. Such annotations are not inherited.
 | `@AutoClose`             | Denotes that the annotated field represents a resource that will be <<writing-tests-built-in-extensions-AutoClose,automatically closed>> after test execution.
 | `@Timeout`               | Used to fail a test, test factory, test template, or lifecycle method if its execution exceeds a given duration. Such annotations are inherited.
-| `@TempDir`               | Used to supply a <<writing-tests-built-in-extensions-TempDirectory,temporary directory>> via field injection or parameter injection in a lifecycle method or test method; located in the `org.junit.jupiter.api.io` package.  Such fields are inherited.
+| `@TempDir`               | Used to supply a <<writing-tests-built-in-extensions-TempDirectory,temporary directory>> via field injection or parameter injection in a test class constructor, lifecycle method, or test method; located in the `org.junit.jupiter.api.io` package. Such fields are inherited.
 | `@ExtendWith`            | Used to <<extensions-registration-declarative,register extensions declaratively>>. Such annotations are inherited.
 | `@RegisterExtension`     | Used to <<extensions-registration-programmatic,register extensions programmatically>> via fields. Such fields are inherited.
 |===

junit-jupiter-api/src/main/java/org/junit/jupiter/api/io/TempDir.java

@@ -28,21 +28,16 @@
 import org.junit.jupiter.api.extension.ParameterResolutionException;
 
 /**
- * {@code @TempDir} can be used to annotate a field in a test class or a
- * parameter in a lifecycle method or test method of type {@link Path} or
- * {@link File} that should be resolved into a temporary directory.
- *
- * <p>Please note that {@code @TempDir} is not supported on constructor
- * parameters. Please use field injection instead by annotating an instance
- * field with {@code @TempDir}.
+ * {@code @TempDir} can be used to annotate a field in a test class or a parameter
+ * in a test class constructor, lifecycle method, or test method of type
+ * {@link Path} or {@link File} that should be resolved into a temporary directory.
  *
  * <h2>Creation</h2>
  *
  * <p>The temporary directory is only created if a field in a test class or a
- * parameter in a lifecycle method or test method is annotated with
- * {@code @TempDir}.
- * An {@link ExtensionConfigurationException} or a
- * {@link ParameterResolutionException} will be thrown in one of the following
+ * parameter in a test class constructor, lifecycle method, or test method is
+ * annotated with {@code @TempDir}. An {@link ExtensionConfigurationException} or
+ * a {@link ParameterResolutionException} will be thrown in one of the following
  * cases:
  *
  * <ul>
@@ -56,15 +51,16 @@
  * </li>
  * </ul>
  *
- * In addition, a {@code ParameterResolutionException} will be thrown for a
- * constructor parameter annotated with {@code @TempDir}.
- *
  * <h2>Scope</h2>
  *
- * <p>By default, a separate temporary directory is created for every
- * declaration of the {@code @TempDir} annotation. If you want to share a
- * temporary directory across all tests in a test class, you should declare the
- * annotation on a {@code static} field or on a parameter of a
+ * <p>By default, a separate temporary directory is created for every declaration
+ * of the {@code @TempDir} annotation. For better isolation when using
+ * {@link org.junit.jupiter.api.TestInstance.Lifecycle#PER_METHOD @TestInstance(Lifecycle.PER_METHOD)}
+ * semantics, you can annotate an instance field or a parameter in the test class
+ * constructor with {@code @TempDir} so that each test method uses a separate
+ * temporary directory. Alternatively, if you want to share a temporary directory
+ * across all tests in a test class, you should declare the annotation on a
+ * {@code static} field or on a parameter of a
  * {@link org.junit.jupiter.api.BeforeAll @BeforeAll} method.
  *
  * <h3>Old behavior</h3>

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/TempDirectory.java

@@ -72,8 +72,9 @@
 
 /**
  * {@code TempDirectory} is a JUnit Jupiter extension that creates and cleans
- * up temporary directories if field in a test class or a parameter in a
- * lifecycle method or test method is annotated with {@code @TempDir}.
+ * up temporary directories if a field in a test class or a parameter in a
+ * test class constructor, lifecycle method, or test method is annotated with
+ * {@code @TempDir}.
  *
  * <p>Consult the Javadoc for {@link TempDir} for details on the contract.
  *