Apply code review

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

@@ -19,14 +19,27 @@
 
 import org.apiguardian.api.API;
 
+/**
+ * {@code AnnotatedElementContext} encapsulates the <em>context</em> in which an
+ * {@link #getAnnotatedElement() AnnotatedElement} is declared.
+ *
+ * <p>For example, an {@code AnnotatedElementContext} is used in
+ * {@link org.junit.jupiter.api.io.TempDirFactory TempDirFactory} to allow inspecting
+ * the field or parameter the {@link org.junit.jupiter.api.io.TempDir TempDir}
+ * annotation is declared on.
+ *
+ * <p>This interface is not intended to be implemented by clients.
+ *
+ * @since 5.10
+ */
 @API(status = EXPERIMENTAL, since = "5.10")
 public interface AnnotatedElementContext {
 
 	/**
 	 * Get the {@link AnnotatedElement} for this context.
 	 *
 	 * <h4>WARNING</h4>
-	 * <p>When searching for annotations on the parameter in this context,
+	 * <p>When searching for annotations on the annotated element in this context,
 	 * favor {@link #isAnnotated(Class)}, {@link #findAnnotation(Class)}, and
 	 * {@link #findRepeatableAnnotations(Class)} over methods in the
 	 * {@link AnnotatedElement} API due to a bug in {@code javac} on JDK versions prior
@@ -48,7 +61,6 @@ public interface AnnotatedElementContext {
 	 *
 	 * @param annotationType the annotation type to search for; never {@code null}
 	 * @return {@code true} if the annotation is present or meta-present
-	 * @since 5.1.1
 	 * @see #findAnnotation(Class)
 	 * @see #findRepeatableAnnotations(Class)
 	 */
@@ -68,7 +80,6 @@ public interface AnnotatedElementContext {
 	 * @param annotationType the annotation type to search for; never {@code null}
 	 * @return an {@code Optional} containing the annotation; never {@code null} but
 	 * potentially empty
-	 * @since 5.1.1
 	 * @see #isAnnotated(Class)
 	 * @see #findRepeatableAnnotations(Class)
 	 */
@@ -89,7 +100,6 @@ public interface AnnotatedElementContext {
 	 * {@code null}
 	 * @return the list of all such annotations found; neither {@code null} nor
 	 * mutable, but potentially empty
-	 * @since 5.1.1
 	 * @see #isAnnotated(Class)
 	 * @see #findAnnotation(Class)
 	 * @see java.lang.annotation.Repeatable

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

@@ -10,6 +10,7 @@
 
 package org.junit.jupiter.api.extension;
 
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.STABLE;
 
 import java.lang.annotation.Annotation;
@@ -91,72 +92,35 @@ default Executable getDeclaringExecutable() {
 
 	/**
 	 * {@inheritDoc}
+	 * @since 5.10
 	 */
+	@API(status = EXPERIMENTAL, since = "5.10")
 	@Override
 	default AnnotatedElement getAnnotatedElement() {
 		return getParameter();
 	}
 
 	/**
-	 * Determine if an annotation of {@code annotationType} is either
-	 * <em>present</em> or <em>meta-present</em> on the {@link Parameter} for
-	 * this context.
-	 *
-	 * <h4>WARNING</h4>
-	 * <p>Favor the use of this method over directly invoking
-	 * {@link Parameter#isAnnotationPresent(Class)} due to a bug in {@code javac}
-	 * on JDK versions prior to JDK 9.
-	 *
-	 * @param annotationType the annotation type to search for; never {@code null}
-	 * @return {@code true} if the annotation is present or meta-present
+	 * {@inheritDoc}
 	 * @since 5.1.1
-	 * @see #findAnnotation(Class)
-	 * @see #findRepeatableAnnotations(Class)
 	 */
+	@API(status = STABLE, since = "5.10")
 	@Override
 	boolean isAnnotated(Class<? extends Annotation> annotationType);
 
 	/**
-	 * Find the first annotation of {@code annotationType} that is either
-	 * <em>present</em> or <em>meta-present</em> on the {@link Parameter} for
-	 * this context.
-	 *
-	 * <h4>WARNING</h4>
-	 * <p>Favor the use of this method over directly invoking annotation lookup
-	 * methods in the {@link Parameter} API due to a bug in {@code javac} on JDK
-	 * versions prior to JDK 9.
-	 *
-	 * @param <A> the annotation type
-	 * @param annotationType the annotation type to search for; never {@code null}
-	 * @return an {@code Optional} containing the annotation; never {@code null} but
-	 * potentially empty
+	 * {@inheritDoc}
 	 * @since 5.1.1
-	 * @see #isAnnotated(Class)
-	 * @see #findRepeatableAnnotations(Class)
 	 */
+	@API(status = STABLE, since = "5.10")
 	@Override
 	<A extends Annotation> Optional<A> findAnnotation(Class<A> annotationType);
 
 	/**
-	 * Find all <em>repeatable</em> {@linkplain Annotation annotations} of
-	 * {@code annotationType} that are either <em>present</em> or
-	 * <em>meta-present</em> on the {@link Parameter} for this context.
-	 *
-	 * <h4>WARNING</h4>
-	 * <p>Favor the use of this method over directly invoking annotation lookup
-	 * methods in the {@link Parameter} API due to a bug in {@code javac} on JDK
-	 * versions prior to JDK 9.
-	 *
-	 * @param <A> the annotation type
-	 * @param annotationType the repeatable annotation type to search for; never
-	 * {@code null}
-	 * @return the list of all such annotations found; neither {@code null} nor
-	 * mutable, but potentially empty
+	 * {@inheritDoc}
 	 * @since 5.1.1
-	 * @see #isAnnotated(Class)
-	 * @see #findAnnotation(Class)
-	 * @see java.lang.annotation.Repeatable
 	 */
+	@API(status = STABLE, since = "5.10")
 	@Override
 	<A extends Annotation> List<A> findRepeatableAnnotations(Class<A> annotationType);
 

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

@@ -55,7 +55,8 @@ public interface TempDirFactory extends Closeable {
 	 * not be associated with the {@link java.nio.file.FileSystems#getDefault()
 	 * default FileSystem}.
 	 *
-	 * @param elementContext   the current annotated element context; never {@code null}
+	 * @param elementContext   the context of the field or parameter where
+	 *                         {@code @TempDir} is declared; never {@code null}
 	 * @param extensionContext the current extension context; never {@code null}
 	 * @return the path to the newly created temporary directory; never {@code null}
 	 * @throws Exception in case of failures