Document that annotations which reference types not present are ignored

Add warnings to the class-level Javadoc for MergedAnnotations,
AnnotatedTypeMetadata, AnnotationMetadata, and MethodMetadata to point
out that annotations may be ignored if their attributes reference types
that are not present in the classpath.

Closes gh-35959

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

@@ -133,6 +133,14 @@ import org.springframework.util.Assert;
  * please use standard Java reflection or Spring's {@link AnnotationUtils}
  * for simple annotation retrieval purposes.
  *
+ * <p><strong>WARNING</strong>: If an annotation cannot be loaded because one of
+ * its attributes references a {@link Class} or {@link Enum}
+ * {@linkplain TypeNotPresentException that is not present in the classpath}, that
+ * annotation will not be accessible via the {@code MergedAnnotations} API.
+ * To assist with diagnosing such scenarios, you can set the log level for
+ * {@code "org.springframework.core.annotation.MergedAnnotation"} to {@code DEBUG},
+ * {@code INFO}, or {@code WARN}.
+
  * @author Phillip Webb
  * @author Sam Brannen
  * @since 5.2

spring-core/src/main/java/org/springframework/core/type/AnnotatedTypeMetadata.java

@@ -37,11 +37,19 @@ import org.springframework.core.annotation.MergedAnnotations;
 import org.springframework.util.MultiValueMap;
 
 /**
- * Defines access to the annotations of a specific type ({@link AnnotationMetadata class}
- * or {@link MethodMetadata method}), in a form that does not necessarily require
+ * Defines access to the annotations on a specific {@link AnnotationMetadata class}
+ * or {@link MethodMetadata method}, in a form that does not necessarily require
  * class loading of the types being inspected. Note, however, that classes for
  * encountered annotations will be loaded.
  *
+ * <p><strong>WARNING</strong>: If an annotation cannot be loaded because one of
+ * its attributes references a {@link Class} or {@link Enum}
+ * {@linkplain TypeNotPresentException that is not present in the classpath}, that
+ * annotation will not be accessible via the {@code AnnotatedTypeMetadata} API.
+ * To assist with diagnosing such scenarios, you can set the log level for
+ * {@code "org.springframework.core.annotation.MergedAnnotation"} to {@code DEBUG},
+ * {@code INFO}, or {@code WARN}.
+ *
  * @author Juergen Hoeller
  * @author Mark Fisher
  * @author Mark Pollack

spring-core/src/main/java/org/springframework/core/type/AnnotationMetadata.java

@@ -25,9 +25,17 @@ import org.springframework.core.annotation.MergedAnnotation;
 import org.springframework.core.annotation.MergedAnnotations;
 
 /**
- * Interface that defines abstract access to the annotations of a specific
+ * Interface that defines abstract access to the annotations on a specific
  * class, in a form that does not require that class to be loaded yet.
  *
+ * <p><strong>WARNING</strong>: If an annotation cannot be loaded because one of
+ * its attributes references a {@link Class} or {@link Enum}
+ * {@linkplain TypeNotPresentException that is not present in the classpath}, that
+ * annotation will not be accessible via the {@code AnnotationMetadata} API.
+ * To assist with diagnosing such scenarios, you can set the log level for
+ * {@code "org.springframework.core.annotation.MergedAnnotation"} to {@code DEBUG},
+ * {@code INFO}, or {@code WARN}.
+ *
  * @author Juergen Hoeller
  * @author Mark Fisher
  * @author Phillip Webb

spring-core/src/main/java/org/springframework/core/type/MethodMetadata.java

@@ -19,9 +19,17 @@ package org.springframework.core.type;
 import java.lang.reflect.Method;
 
 /**
- * Interface that defines abstract access to the annotations of a specific
+ * Interface that defines abstract access to the annotations on a specific
  * method, in a form that does not require that method's class to be loaded yet.
  *
+ * <p><strong>WARNING</strong>: If an annotation cannot be loaded because one of
+ * its attributes references a {@link Class} or {@link Enum}
+ * {@linkplain TypeNotPresentException that is not present in the classpath},
+ * that annotation will not be accessible via the {@code MethodMetadata} API.
+ * To assist with diagnosing such scenarios, you can set the log level for
+ * {@code "org.springframework.core.annotation.MergedAnnotation"} to {@code DEBUG},
+ * {@code INFO}, or {@code WARN}.
+ *
  * @author Juergen Hoeller
  * @author Mark Pollack
  * @author Chris Beams