Document that AnnotationSupport.isAnnotated() does not find repeatable annotations (#4243)

Resolves #4058.

---------

Co-authored-by: Sam Brannen <[email protected]>

Author: YongGoose

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

@@ -871,6 +871,9 @@ and fields in a class or interface. Some of these methods search on implemented
 interfaces and within class hierarchies to find annotations. Consult the Javadoc for
 `{AnnotationSupport}` for further details.
 
+NOTE: The `isAnnotated()` methods do not find repeatable annotations. To check for repeatable annotations,
+use one of the `findRepeatableAnnotations()` methods and verify that the returned list is not empty.
+
 NOTE: See also: <<extensions-supported-utilities-search-semantics>>
 
 [[extensions-supported-utilities-classes]]

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

@@ -55,6 +55,10 @@ public interface AnnotatedElementContext {
 	 * <em>present</em> or <em>meta-present</em> on the {@link AnnotatedElement} for
 	 * this context.
 	 *
+	 * <p><strong>Note:</strong> This method does not find repeatable annotations.
+	 * To check for repeatable annotations, use {@link #findRepeatableAnnotations(Class)}
+	 * and verify that the returned list is not empty.
+	 *
 	 * <h4>WARNING</h4>
 	 * <p>Favor the use of this method over directly invoking
 	 * {@link AnnotatedElement#isAnnotationPresent(Class)} due to a bug in {@code javac}

junit-platform-commons/src/main/java/org/junit/platform/commons/support/AnnotationSupport.java

@@ -54,13 +54,18 @@ private AnnotationSupport() {
 	 * <em>present</em> or <em>meta-present</em> on the supplied optional
 	 * {@code element}.
 	 *
+	 * <p><strong>Note:</strong> This method does not find repeatable annotations.
+	 * To check for repeatable annotations, use {@link #findRepeatableAnnotations(Optional, Class)}
+	 * and verify that the returned list is not empty.
+	 *
 	 * @param element an {@link Optional} containing the element on which to
 	 * search for the annotation; may be {@code null} or <em>empty</em>
 	 * @param annotationType the annotation type to search for; never {@code null}
 	 * @return {@code true} if the annotation is present or meta-present
 	 * @since 1.3
 	 * @see #isAnnotated(AnnotatedElement, Class)
 	 * @see #findAnnotation(Optional, Class)
+	 * @see #findRepeatableAnnotations(Optional, Class)
 	 */
 	@API(status = MAINTAINED, since = "1.3")
 	public static boolean isAnnotated(Optional<? extends AnnotatedElement> element,
@@ -74,12 +79,17 @@ public static boolean isAnnotated(Optional<? extends AnnotatedElement> element,
 	 * <em>present</em> or <em>meta-present</em> on the supplied
 	 * {@code element}.
 	 *
+	 * <p><strong>Note:</strong> This method does not find repeatable annotations.
+	 * To check for repeatable annotations, use {@link #findRepeatableAnnotations(AnnotatedElement, Class)}
+	 * and verify that the returned list is not empty.
+	 *
 	 * @param element the element on which to search for the annotation; may be
 	 * {@code null}
 	 * @param annotationType the annotation type to search for; never {@code null}
 	 * @return {@code true} if the annotation is present or meta-present
 	 * @see #isAnnotated(Optional, Class)
 	 * @see #findAnnotation(AnnotatedElement, Class)
+	 * @see #findRepeatableAnnotations(AnnotatedElement, Class)
 	 */
 	public static boolean isAnnotated(AnnotatedElement element, Class<? extends Annotation> annotationType) {
 		return AnnotationUtils.isAnnotated(element, annotationType);