Polish JavaDoc for Jupiter programming model APIs

Author: sbrannen

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

@@ -22,8 +22,9 @@
 
 /**
  * {@code @AfterEach} is used to signal that the annotated method should be
- * executed <em>after</em> <strong>each</strong> {@code @Test} method in
- * the current test class.
+ * executed <em>after</em> <strong>each</strong> {@code @Test},
+ * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory},
+ * and {@code @TestTemplate} method in the current test class.
  *
  * <h3>Method Signatures</h3>
  *
@@ -54,6 +55,9 @@
  * @see BeforeAll
  * @see AfterAll
  * @see Test
+ * @see RepeatedTest
+ * @see TestFactory
+ * @see TestTemplate
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)

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

@@ -22,8 +22,9 @@
 
 /**
  * {@code @BeforeEach} is used to signal that the annotated method should be
- * executed <em>before</em> <strong>each</strong> {@code @Test} method in
- * the current test class.
+ * executed <em>before</em> <strong>each</strong> {@code @Test},
+ * {@code @RepeatedTest}, {@code @ParameterizedTest}, {@code @TestFactory},
+ * and {@code @TestTemplate} method in the current test class.
  *
  * <h3>Method Signatures</h3>
  *
@@ -54,6 +55,9 @@
  * @see BeforeAll
  * @see AfterAll
  * @see Test
+ * @see RepeatedTest
+ * @see TestFactory
+ * @see TestTemplate
  */
 @Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
 @Retention(RetentionPolicy.RUNTIME)

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

@@ -24,10 +24,14 @@
  * {@code @Disabled} is used to signal that the annotated test class or
  * test method is currently <em>disabled</em> and should not be executed.
  *
+ * <p>{@code @Disabled} may optionally be declared with a {@linkplain #value
+ * reason} to document why the annotated test class or test method is disabled.
+ *
  * <p>When applied at the class level, all test methods within that class
  * are automatically disabled as well.
  *
  * @since 5.0
+ * @see #value
  * @see org.junit.jupiter.api.condition.EnabledIf
  * @see org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable
  * @see org.junit.jupiter.api.condition.EnabledIfSystemProperty

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

@@ -22,9 +22,11 @@
 
 /**
  * {@code @Nested} is used to signal that the annotated class is a nested,
- * non-static test class.
+ * non-static test class (i.e., an <em>inner class</em>).
  *
  * @since 5.0
+ * @see Test
+ * @see TestInstance
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)

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

@@ -20,15 +20,22 @@
 
 /**
  * {@code TestInfo} is used to inject information about the current test or
- * container into to {@code @Test}, {@code @BeforeEach}, {@code @AfterEach},
- * {@code @BeforeAll}, and {@code @AfterAll} methods.
+ * container into to {@code @Test}, {@code @RepeatedTest},
+ * {@code @ParameterizedTest}, {@code @TestFactory}, {@code @BeforeEach},
+ * {@code @AfterEach}, {@code @BeforeAll}, and {@code @AfterAll} methods.
  *
  * <p>If a method parameter is of type {@link TestInfo}, JUnit will supply
- * an instance of {@code TestInfo} corresponding to the current test as the
- * value for the parameter.
+ * an instance of {@code TestInfo} corresponding to the current test or
+ * container as the value for the parameter.
  *
  * @since 5.0
  * @see Test
+ * @see RepeatedTest
+ * @see TestFactory
+ * @see BeforeEach
+ * @see AfterEach
+ * @see BeforeAll
+ * @see AfterAll
  * @see DisplayName
  * @see Tag
  */
@@ -96,7 +103,7 @@ public interface TestInfo {
 	Optional<Class<?>> getTestClass();
 
 	/**
-	 * Get the {@link Method} associated with the current test, if available.
+	 * Get the {@link Method} associated with the current test or container, if available.
 	 */
 	Optional<Method> getTestMethod();
 

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

@@ -18,26 +18,41 @@
 import org.apiguardian.api.API;
 
 /**
- * Parameters of type {@code TestReporter} can be injected into methods of
- * test classes annotated with {@link BeforeEach @BeforeEach},
- * {@link AfterEach @AfterEach}, and {@link Test @Test}.
+ * Parameters of type {@code TestReporter} can be injected into
+ * {@link BeforeEach @BeforeEach} and {@link AfterEach @AfterEach} lifecycle
+ * methods as well as methods annotated with {@link Test @Test},
+ * {@link RepeatedTest @RepeatedTest},
+ * {@link org.junit.jupiter.params.ParameterizedTest @ParameterizedTest},
+ * {@link TestFactory @TestFactory}, etc.
  *
- * <p>Within such methods this instance of type {@code TestReporter} can be
- * used to publish report entries.
+ * <p>Within such methods the injected {@code TestReporter} can be used to
+ * publish report entries.
  *
  * @since 5.0
+ * @see #publishEntry(Map)
+ * @see #publishEntry(String, String)
  */
 @FunctionalInterface
 @API(status = STABLE, since = "5.0")
 public interface TestReporter {
 
 	/**
-	 * Publish the supplied values as a report entry.
+	 * Publish the supplied map of key-value pairs as a report entry.
 	 *
-	 * @param  values the map to be published for this entry
+	 * @param map the key-value pairs to be published; never {@code null};
+	 * keys and values within entries in the map also must not be
+	 * {@code null} or blank
+	 * @see #publishEntry(String, String)
 	 */
-	void publishEntry(Map<String, String> values);
+	void publishEntry(Map<String, String> map);
 
+	/**
+	 * Publish the supplied key-value pair as a report entry.
+	 *
+	 * @param key the key of the entry to publish
+	 * @param value the value of the entry to publish
+	 * @see #publishEntry(Map)
+	 */
 	default void publishEntry(String key, String value) {
 		this.publishEntry(Collections.singletonMap(key, value));
 	}