Polish contribution

See #3311, #3313

Author: sbrannen

documentation/src/docs/asciidoc/release-notes/release-notes-5.10.0-RC1.adoc

@@ -24,8 +24,6 @@ JUnit repository on GitHub.
 ==== New Features and Improvements
 
 * New `@SelectMethod` selector support in the `@Suite` test engine.
-* Add `@SelectMethod` selector support to `@Suite` test engine
-* `@TempDir` can now be used in meta-annotations
 
 
 [[release-notes-5.10.0-RC1-junit-jupiter]]
@@ -41,6 +39,10 @@ JUnit repository on GitHub.
 
 ==== New Features and Improvements
 
+* `@TempDir` can now be used as a meta-annotation in order to create custom _composed
+  annotations_. See the `@JimfsTempDir` example in the
+  <<../user-guide/index.adoc#writing-tests-built-in-extensions-TempDirectory, User Guide>>
+  for details.
 * Lifecycle and thread-safety semantics are now documented for the `TempDirFactory` SPI.
 
 

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

@@ -2627,8 +2627,8 @@ they are instantiated, but they can assume that their `createTempDirectory(...)`
 thread.
 
 The default implementation available in Jupiter delegates the directory creation to
-`java.nio.file.Files::createTempDirectory`, passing `junit` as the prefix string
-to be used in generating the directory's name.
+`java.nio.file.Files::createTempDirectory`, passing `junit` as the prefix string to be
+used in generating the directory's name.
 
 The following example defines a factory that uses the test name as the directory name
 prefix instead of the `junit` constant value.
@@ -2640,25 +2640,31 @@ include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_factory_name_p
 ----
 
 It's also possible to use an in-memory file system like `{Jimfs}` for the creation of the
-temporary directory. The following example shows how to do it.
+temporary directory. The following example demonstrates how to achieve that.
 
 [source,java,indent=0]
 .A test class with a temporary directory created with the Jimfs in-memory file system
 ----
 include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_factory_jimfs]
 ----
 
-`@TempDir` can also be used in meta-annotations to reduce repetition.
+`@TempDir` can also be used as a <<writing-tests-meta-annotations, meta-annotation>> to
+reduce repetition. The following code listing shows how to create a custom `@JimfsTempDir`
+annotation that can be used as a drop-in replacement for
+`@TempDir(factory = JimfsTempDirFactory.class)`.
 
 [source,java,indent=0]
-.A definition of a meta-annotation using `@TempDir`
+.A custom annotation meta-annotated with `@TempDir`
 ----
-include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_meta_annotation]
+include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_composed_annotation]
 ----
+
+The following example demonstrates how to use the custom `@JimfsTempDir` annotation.
+
 [source,java,indent=0]
-.A test class using a meta-annotation
+.A test class using the custom annotation
 ----
-include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_meta_annotation_usage]
+include::{testDir}/example/TempDirectoryDemo.java[tags=user_guide_composed_annotation_usage]
 ----
 
 You can use the `junit.jupiter.tempdir.factory.default`

documentation/src/test/java/example/TempDirectoryDemo.java

@@ -147,17 +147,16 @@ public void close() throws IOException {
 	}
 	// end::user_guide_factory_jimfs[]
 
-	// tag::user_guide_meta_annotation[]
+	// tag::user_guide_composed_annotation[]
 	@Target({ ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.PARAMETER })
 	@Retention(RetentionPolicy.RUNTIME)
 	@TempDir(factory = JimfsTempDirFactory.class)
 	@interface JimfsTempDir {
-
 	}
-	// end::user_guide_meta_annotation[]
+	// end::user_guide_composed_annotation[]
 
 	static
-	// tag::user_guide_meta_annotation_usage[]
+	// tag::user_guide_composed_annotation_usage[]
 	class JimfsTempDirAnnotationDemo {
 
 		@Test
@@ -166,6 +165,6 @@ void test(@JimfsTempDir Path tempDir) {
 		}
 
 	}
-	// end::user_guide_meta_annotation_usage[]
+	// end::user_guide_composed_annotation_usage[]
 
 }

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

@@ -90,7 +90,7 @@
  *
  * @since 5.4
  */
-@Target({ ElementType.FIELD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE })
+@Target({ ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.PARAMETER })
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
 @API(status = STABLE, since = "5.10")

junit-jupiter-engine/src/test/java/org/junit/jupiter/engine/extension/TempDirectoryMetaAnnotationTests.java

@@ -34,19 +34,19 @@ class TempDirectoryMetaAnnotationTests extends AbstractJupiterTestEngineTests {
 
 	@Test
 	void annotationOnField() {
-		executeTestsForClass(AnnotationOnFieldTestCase.class).testEvents().assertStatistics(
-			stats -> stats.started(1).succeeded(1));
+		executeTestsForClass(AnnotationOnFieldTestCase.class).testEvents()//
+				.assertStatistics(stats -> stats.started(1).succeeded(1));
 	}
 
 	@Test
 	void annotationOnParameter() {
-		executeTestsForClass(AnnotationOnParameterTestCase.class).testEvents().assertStatistics(
-			stats -> stats.started(1).succeeded(1));
+		executeTestsForClass(AnnotationOnParameterTestCase.class).testEvents()//
+				.assertStatistics(stats -> stats.started(1).succeeded(1));
 	}
 
 	static class AnnotationOnFieldTestCase {
 
-		@MetaTempDir
+		@CustomTempDir
 		private Path tempDir;
 
 		@Test
@@ -59,7 +59,7 @@ void test() {
 	static class AnnotationOnParameterTestCase {
 
 		@Test
-		void test(@MetaTempDir Path tempDir) {
+		void test(@CustomTempDir Path tempDir) {
 			assertTrue(Files.exists(tempDir));
 		}
 
@@ -68,8 +68,7 @@ void test(@MetaTempDir Path tempDir) {
 	@TempDir
 	@Target({ ElementType.FIELD, ElementType.PARAMETER })
 	@Retention(RetentionPolicy.RUNTIME)
-	@interface MetaTempDir {
-
+	@interface CustomTempDir {
 	}
 
 }