Cross reference annotation search APIs in Javadoc

Closes gh-34421

Author: sbrannen

spring-core/src/main/java/org/springframework/core/annotation/AnnotatedElementUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2022 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -36,8 +36,12 @@
  *
  * <p>{@code AnnotatedElementUtils} defines the public API for Spring's
  * meta-annotation programming model with support for <em>annotation attribute
- * overrides</em>. If you do not need support for annotation attribute
- * overrides, consider using {@link AnnotationUtils} instead.
+ * overrides</em> and {@link AliasFor @AliasFor}. Note, however, that
+ * {@code AnnotatedElementUtils} is effectively a facade for the
+ * {@link MergedAnnotations} API. For fine-grained support consider using the
+ * {@code MergedAnnotations} API directly. If you do not need support for
+ * annotation attribute overrides, {@code @AliasFor}, or merged annotations,
+ * consider using {@link AnnotationUtils} instead.
  *
  * <p>Note that the features of this class are not provided by the JDK's
  * introspection facilities themselves.
@@ -87,6 +91,7 @@
  * @since 4.0
  * @see AliasFor
  * @see AnnotationAttributes
+ * @see MergedAnnotations
  * @see AnnotationUtils
  * @see BridgeMethodResolver
  */

spring-core/src/main/java/org/springframework/core/annotation/AnnotationUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -60,7 +60,7 @@
  * <h3>Terminology</h3>
  * The terms <em>directly present</em>, <em>indirectly present</em>, and
  * <em>present</em> have the same meanings as defined in the class-level
- * javadoc for {@link AnnotatedElement} (in Java 8).
+ * javadoc for {@link AnnotatedElement}.
  *
  * <p>An annotation is <em>meta-present</em> on an element if the annotation
  * is declared as a meta-annotation on some other annotation which is
@@ -73,7 +73,8 @@
  * provide support for finding annotations used as meta-annotations. Consult the
  * javadoc for each method in this class for details. For fine-grained support for
  * meta-annotations with <em>attribute overrides</em> in <em>composed annotations</em>,
- * consider using {@link AnnotatedElementUtils}'s more specific methods instead.
+ * consider using the {@link MergedAnnotations} API directly or the more specific
+ * methods in {@link AnnotatedElementUtils} instead.
  *
  * <h3>Attribute Aliases</h3>
  * <p>All public methods in this class that return annotations, arrays of
@@ -97,6 +98,7 @@
  * @since 2.0
  * @see AliasFor
  * @see AnnotationAttributes
+ * @see MergedAnnotations
  * @see AnnotatedElementUtils
  * @see BridgeMethodResolver
  * @see java.lang.reflect.AnnotatedElement#getAnnotations()

spring-core/src/main/java/org/springframework/core/annotation/MergedAnnotations.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -37,7 +37,7 @@
  * <ul>
  * <li>Explicit and Implicit {@link AliasFor @AliasFor} declarations on one or
  * more attributes within the annotation</li>
- * <li>Explicit {@link AliasFor @AliasFor} declarations for a meta-annotation</li>
+ * <li>Explicit {@code @AliasFor} declarations for a meta-annotation</li>
  * <li>Convention based attribute aliases for a meta-annotation</li>
  * <li>From a meta-annotation declaration</li>
  * </ul>
@@ -140,6 +140,9 @@
  * @see MergedAnnotationCollectors
  * @see MergedAnnotationPredicates
  * @see MergedAnnotationSelectors
+ * @see AliasFor
+ * @see AnnotationUtils
+ * @see AnnotatedElementUtils
  */
 public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>> {
 
@@ -560,6 +563,7 @@ private Search(SearchStrategy searchStrategy) {
 		 * @see #withRepeatableContainers(RepeatableContainers)
 		 * @see #withAnnotationFilter(AnnotationFilter)
 		 * @see #from(AnnotatedElement)
+		 * @see org.springframework.test.context.TestContextAnnotationUtils#searchEnclosingClass(Class)
 		 */
 		public Search withEnclosingClasses(Predicate<Class<?>> searchEnclosingClass) {
 			Assert.notNull(searchEnclosingClass, "Predicate must not be null");

spring-test/src/main/java/org/springframework/test/context/TestContextAnnotationUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,19 +43,20 @@
 
 /**
  * {@code TestContextAnnotationUtils} is a collection of utility methods that
- * complements the standard support already available in {@link AnnotationUtils}
- * and {@link AnnotatedElementUtils}, while transparently honoring
- * {@link NestedTestConfiguration @NestedTestConfiguration} semantics.
+ * complements the standard support already available in {@link MergedAnnotations},
+ * {@link AnnotationUtils}, and {@link AnnotatedElementUtils}, while transparently
+ * honoring {@link NestedTestConfiguration @NestedTestConfiguration} semantics.
  *
  * <p>Mainly for internal use within the <em>Spring TestContext Framework</em>
  * but also supported for third-party integrations with the TestContext framework.
  *
- * <p>Whereas {@code AnnotationUtils} and {@code AnnotatedElementUtils} provide
- * utilities for <em>getting</em> or <em>finding</em> annotations,
- * {@code TestContextAnnotationUtils} goes a step further by providing support
- * for determining the <em>root class</em> on which an annotation is declared,
- * either directly or indirectly via a <em>composed annotation</em>. This
- * additional information is encapsulated in an {@link AnnotationDescriptor}.
+ * <p>Whereas {@code MergedAnnotations}, {@code AnnotationUtils} and
+ * {@code AnnotatedElementUtils} provide utilities for <em>getting</em> or
+ * <em>finding</em> annotations, {@code TestContextAnnotationUtils} goes a step
+ * further by providing support for determining the <em>root class</em> on which
+ * an annotation is declared, either directly or indirectly via a
+ * <em>composed annotation</em>. This additional information is encapsulated in
+ * an {@link AnnotationDescriptor}.
  *
  * <p>The additional information provided by an {@code AnnotationDescriptor} is
  * required by the <em>Spring TestContext Framework</em> in order to be able to
@@ -67,7 +68,11 @@
  * example, {@link ContextConfiguration#inheritLocations}.
  *
  * @author Sam Brannen
- * @since 5.3, though originally since 4.0 as {@code org.springframework.test.util.MetaAnnotationUtils}
+ * @since 5.3
+ * @see MergedAnnotations
+ * @see MergedAnnotations.Search
+ * @see MergedAnnotations.Search#withEnclosingClasses(Predicate)
+ * @see #searchEnclosingClass(Class)
  * @see AnnotationUtils
  * @see AnnotatedElementUtils
  * @see AnnotationDescriptor