Polish contribution

documentation/src/docs/asciidoc/user-guide/extensions.adoc

@@ -489,48 +489,47 @@ constructor invocations, using the `{ExecutableInvoker}` available via the
 
 If multiple implementations of `ParameterResolver` that support the same type are
 registered for a test, a `ParameterResolutionException` will be thrown, with a
-message to indicate that competing resolvers have been discovered. See the following example:
+message to indicate that competing resolvers have been discovered. See the following
+example:
 
 [source,java,indent=0]
-.Conflicting parameter resolution due to duplicate types
+.Conflicting parameter resolution due to multiple resolvers claiming support for integers
 ----
-include::{testDir}/example/extensions/ParameterResolverDuplicateTypeInteger.java[tags=user_guide]
+include::{testDir}/example/extensions/ParameterResolverConflictDemo.java[tags=user_guide]
 ----
 
 If the conflicting `ParameterResolver` implementations are applied to different test
-methods, the methods can be separated into <<writing-tests-nested, `nested tests`>>
-as follows:
+methods as shown in the following example, no conflict occurs.
 
 [source,java,indent=0]
-.Nested parameter resolution to resolve duplicate types
+.Fine-grained registration to avoid conflict
 ----
-include::{testDir}/example/extensions/ParameterResolverNestedClasses.java[tags=user_guide]
+include::{testDir}/example/extensions/ParameterResolverNoConflictDemo.java[tags=user_guide]
 ----
 
-If the conflicting `ParameterResolver` implementations are applied within the same test
-method, implement a custom type or custom annotation as illustrated by
-`{CustomTypeParameterResolver}` and `{CustomAnnotationParameterResolver}`. A custom type
-wraps the duplicate type:
+If the conflicting `ParameterResolver` implementations need to be applied to the same test
+method, you can implement a custom type or custom annotation as illustrated by
+`{CustomTypeParameterResolver}` and `{CustomAnnotationParameterResolver}`, respectively.
 
 [source,java,indent=0]
 .Custom type to resolve duplicate types
 ----
-include::{testDir}/example/extensions/ParameterResolverCustomType.java[tags=user_guide]
+include::{testDir}/example/extensions/ParameterResolverCustomTypeDemo.java[tags=user_guide]
 ----
 
 A custom annotation makes the duplicate type distinguishable from its counterpart:
 
 [source,java,indent=0]
 .Custom annotation to resolve duplicate types
 ----
-include::{testDir}/example/extensions/ParameterResolverCustomAnnotation.java[tags=user_guide]
+include::{testDir}/example/extensions/ParameterResolverCustomAnnotationDemo.java[tags=user_guide]
 ----
 
-JUnit includes some built-in parameter resolvers that can cause conflicts if an attempt
-is made to redefine their supported types. For example, `{TestInfo}` provides metadata
-about tests. See <<writing-tests-dependency-injection>> for details. Third-party
-frameworks such as Spring may also define parameter resolvers. Apply one of the
-techniques in this section to resolve any conflicts.
+JUnit includes some built-in parameter resolvers that can cause conflicts if a resolver
+attempts to claim their supported types. For example, `{TestInfo}` provides metadata about
+tests. See <<writing-tests-dependency-injection>> for details. Third-party frameworks such
+as Spring may also define parameter resolvers. Apply one of the techniques in this section
+to resolve any conflicts.
 
 Parameterized tests are another potential source of conflict. Ensure that tests annotated
 with `@ParameterizedTest` are not also annotated with `@Test` and see

documentation/src/test/java/example/extensions/ParameterResolverDuplicateTypeInteger.java → documentation/src/test/java/example/extensions/ParameterResolverConflictDemo.java

@@ -12,15 +12,20 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
+import extensions.ExpectToFail;
+
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.junit.jupiter.api.extension.ExtensionContext;
 import org.junit.jupiter.api.extension.ParameterContext;
 import org.junit.jupiter.api.extension.ParameterResolver;
 
 // tag::user_guide[]
-public class ParameterResolverDuplicateTypeInteger {
+public class ParameterResolverConflictDemo {
 
+	// end::user_guide[]
+	@ExpectToFail
+	// tag::user_guide[]
 	@Test
 	@ExtendWith({ FirstIntegerResolver.class, SecondIntegerResolver.class })
 	void testInt(int i) {

documentation/src/test/java/example/extensions/ParameterResolverCustomAnnotationDemo.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2015-2024 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package example.extensions;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.api.extension.ExtensionContext;
+import org.junit.jupiter.api.extension.ParameterContext;
+import org.junit.jupiter.api.extension.ParameterResolver;
+
+// tag::user_guide[]
+public class ParameterResolverCustomAnnotationDemo {
+
+	@Test
+	void testInt(@FirstInteger Integer first, @SecondInteger Integer second) {
+		assertEquals(1, first);
+		assertEquals(2, second);
+	}
+
+	@Target(ElementType.PARAMETER)
+	@Retention(RetentionPolicy.RUNTIME)
+	@ExtendWith(FirstInteger.Extension.class)
+	public @interface FirstInteger {
+
+		class Extension implements ParameterResolver {
+
+			@Override
+			public boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {
+				return parameterContext.getParameter().getType().equals(Integer.class)
+						&& !parameterContext.isAnnotated(SecondInteger.class);
+			}
+
+			@Override
+			public Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {
+				return 1;
+			}
+		}
+	}
+
+	@Target(ElementType.PARAMETER)
+	@Retention(RetentionPolicy.RUNTIME)
+	@ExtendWith(SecondInteger.Extension.class)
+	public @interface SecondInteger {
+
+		class Extension implements ParameterResolver {
+
+			@Override
+			public boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {
+				return parameterContext.isAnnotated(SecondInteger.class);
+			}
+
+			@Override
+			public Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {
+				return 2;
+			}
+		}
+	}
+}
+// end::user_guide[]

documentation/src/test/java/example/extensions/ParameterResolverCustomType.java → documentation/src/test/java/example/extensions/ParameterResolverCustomTypeDemo.java

@@ -19,13 +19,13 @@
 import org.junit.jupiter.api.extension.ParameterResolver;
 
 // tag::user_guide[]
-public class ParameterResolverCustomType {
+public class ParameterResolverCustomTypeDemo {
 
 	@Test
 	@ExtendWith({ FirstIntegerResolver.class, SecondIntegerResolver.class })
 	void testInt(Integer i, WrappedInteger wrappedInteger) {
 		assertEquals(1, i);
-		assertEquals(2, wrappedInteger.getValue());
+		assertEquals(2, wrappedInteger.value);
 	}
 
 	static class FirstIntegerResolver implements ParameterResolver {
@@ -56,15 +56,12 @@ public Object resolveParameter(ParameterContext parameterContext, ExtensionConte
 
 	static class WrappedInteger {
 
-		private int value;
+		private final int value;
 
 		public WrappedInteger(int value) {
 			this.value = value;
 		}
 
-		public int getValue() {
-			return value;
-		}
 	}
 }
 // end::user_guide[]

documentation/src/test/java/example/extensions/ParameterResolverNestedClasses.java → documentation/src/test/java/example/extensions/ParameterResolverNoConflictDemo.java

@@ -12,42 +12,25 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
-import org.junit.jupiter.api.DisplayName;
-import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.TestInfo;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.junit.jupiter.api.extension.ExtensionContext;
 import org.junit.jupiter.api.extension.ParameterContext;
 import org.junit.jupiter.api.extension.ParameterResolver;
 
 // tag::user_guide[]
-public class ParameterResolverNestedClasses {
+public class ParameterResolverNoConflictDemo {
 
 	@Test
-	@DisplayName("Outer class test")
-	void testOuterClass(TestInfo testInfo) {
-		assertEquals("Outer class test", testInfo.getDisplayName());
+	@ExtendWith(FirstIntegerResolver.class)
+	void firstResolution(int i) {
+		assertEquals(1, i);
 	}
 
-	@Nested
-	class FirstResolution {
-
-		@Test
-		@ExtendWith(FirstIntegerResolver.class)
-		void testIntNested(int i) {
-			assertEquals(1, i);
-		}
-	}
-
-	@Nested
-	class SecondResolution {
-
-		@Test
-		@ExtendWith(SecondIntegerResolver.class)
-		void testIntNested(int i) {
-			assertEquals(2, i);
-		}
+	@Test
+	@ExtendWith(SecondIntegerResolver.class)
+	void secondResolution(int i) {
+		assertEquals(2, i);
 	}
 
 	static class FirstIntegerResolver implements ParameterResolver {