Improve javadoc for when to use class names rather than class references

Closes gh-48395

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfiguration.java

@@ -78,6 +78,12 @@ public @interface AutoConfiguration {
 
 	/**
 	 * The auto-configuration classes that should have not yet been applied.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation. In order to use this annotation as a meta-annotation,
+	 * only use the {@link #beforeName} attribute.
 	 * @return the classes
 	 */
 	@AliasFor(annotation = AutoConfigureBefore.class, attribute = "value")
@@ -95,6 +101,12 @@ public @interface AutoConfiguration {
 
 	/**
 	 * The auto-configuration classes that should have already been applied.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation. In order to use this annotation as a meta-annotation,
+	 * only use the {@link #afterName} attribute.
 	 * @return the classes
 	 */
 	@AliasFor(annotation = AutoConfigureAfter.class, attribute = "value")

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureAfter.java

@@ -45,6 +45,12 @@ public @interface AutoConfigureAfter {
 
 	/**
 	 * The auto-configuration classes that should have already been applied.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation. In order to use this annotation as a meta-annotation,
+	 * only use the {@link #name} attribute.
 	 * @return the classes
 	 */
 	Class<?>[] value() default {};

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureBefore.java

@@ -45,6 +45,12 @@ public @interface AutoConfigureBefore {
 
 	/**
 	 * The auto-configuration classes that should have not yet been applied.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation. In order to use this annotation as a meta-annotation,
+	 * only use the {@link #name} attribute.
 	 * @return the classes
 	 */
 	Class<?>[] value() default {};

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/EnableAutoConfiguration.java

@@ -90,6 +90,12 @@ public @interface EnableAutoConfiguration {
 
 	/**
 	 * Exclude specific auto-configuration classes such that they will never be applied.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation. In order to use this annotation as a meta-annotation,
+	 * only use the {@link #excludeName()} attribute.
 	 * @return the classes to exclude
 	 */
 	Class<?>[] exclude() default {};

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/SpringBootApplication.java

@@ -34,7 +34,6 @@ import org.springframework.context.annotation.ComponentScan.Filter;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.context.annotation.FilterType;
 import org.springframework.core.annotation.AliasFor;
-import org.springframework.data.repository.Repository;
 
 /**
  * Indicates a {@link Configuration configuration} class that declares one or more
@@ -60,6 +59,12 @@ public @interface SpringBootApplication {
 
 	/**
 	 * Exclude specific auto-configuration classes such that they will never be applied.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation. In order to use this annotation as a meta-annotation,
+	 * only use the {@link #excludeName} attribute.
 	 * @return the classes to exclude
 	 */
 	@AliasFor(annotation = EnableAutoConfiguration.class)

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnBean.java

@@ -72,6 +72,12 @@ public @interface ConditionalOnBean {
 	 * The class types of beans that should be checked. The condition matches when beans
 	 * of all classes specified are contained in the {@link BeanFactory}. Beans that are
 	 * not autowire candidates or that are not default candidates are ignored.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation. In order to use this annotation as a meta-annotation,
+	 * only use the {@link #type} attribute.
 	 * @return the class types of beans to check
 	 * @see Bean#autowireCandidate()
 	 * @see BeanDefinition#isAutowireCandidate
@@ -97,6 +103,11 @@ public @interface ConditionalOnBean {
 	 * when all the annotations specified are defined on beans in the {@link BeanFactory}.
 	 * Beans that are not autowire candidates or that are not default candidates are
 	 * ignored.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation.
 	 * @return the class-level annotation types to check
 	 * @see Bean#autowireCandidate()
 	 * @see BeanDefinition#isAutowireCandidate
@@ -124,6 +135,11 @@ public @interface ConditionalOnBean {
 	 * parameters. For example, an annotation declaring {@code value=Name.class} and
 	 * {@code parameterizedContainer=NameRegistration.class} would detect both
 	 * {@code Name} and {@code NameRegistration<Name>}.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation.
 	 * @return the container types
 	 * @since 2.1.0
 	 */

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java

@@ -66,11 +66,13 @@ import org.springframework.context.annotation.Conditional;
 public @interface ConditionalOnClass {
 
 	/**
-	 * The classes that must be present. Since this annotation is parsed by loading class
+	 * The classes that must be present.
-	 * bytecode, it is safe to specify classes here that may ultimately not be on the
+	 * <p>
-	 * classpath, only if this annotation is directly on the affected component and
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
-	 * <b>not</b> if this annotation is used as a composed, meta-annotation. In order to
+	 * classes here that may ultimately not be on the classpath, only if this annotation
-	 * use this annotation as a meta-annotation, only use the {@link #name} attribute.
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation. In order to use this annotation as a meta-annotation,
+	 * only use the {@link #name} attribute.
 	 * @return the classes that must be present
 	 */
 	Class<?>[] value() default {};

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnMissingBean.java

@@ -73,6 +73,12 @@ public @interface ConditionalOnMissingBean {
 	 * The class types of beans that should be checked. The condition matches when no bean
 	 * of each class specified is contained in the {@link BeanFactory}. Beans that are not
 	 * autowire candidates or that are not default candidates are ignored.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation. In order to use this annotation as a meta-annotation,
+	 * only use the {@link #type} attribute.
 	 * @return the class types of beans to check
 	 * @see Bean#autowireCandidate()
 	 * @see BeanDefinition#isAutowireCandidate
@@ -95,6 +101,12 @@ public @interface ConditionalOnMissingBean {
 
 	/**
 	 * The class types of beans that should be ignored when identifying matching beans.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation. In order to use this annotation as a meta-annotation,
+	 * only use the {@link #ignoredType} attribute.
 	 * @return the class types of beans to ignore
 	 * @since 1.2.5
 	 */
@@ -113,6 +125,11 @@ public @interface ConditionalOnMissingBean {
 	 * when each annotation specified is missing from all beans in the
 	 * {@link BeanFactory}. Beans that are not autowire candidates or that are not default
 	 * candidates are ignored.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation.
 	 * @return the class-level annotation types to check
 	 * @see Bean#autowireCandidate()
 	 * @see BeanDefinition#isAutowireCandidate
@@ -140,6 +157,11 @@ public @interface ConditionalOnMissingBean {
 	 * parameters. For example, an annotation declaring {@code value=Name.class} and
 	 * {@code parameterizedContainer=NameRegistration.class} would detect both
 	 * {@code Name} and {@code NameRegistration<Name>}.
+	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation.
 	 * @return the container types
 	 * @since 2.1.0
 	 */

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnSingleCandidate.java

@@ -57,6 +57,12 @@ public @interface ConditionalOnSingleCandidate {
 	 * exists in case of multiple instances. Beans that are not autowire candidates, that
 	 * are not default candidates, or that are fallback candidates are ignored.
 	 * <p>
+	 * Since this annotation is parsed by loading class bytecode, it is safe to specify
+	 * classes here that may ultimately not be on the classpath, only if this annotation
+	 * is directly on the affected component and <b>not</b> if this annotation is used as
+	 * a composed, meta-annotation. In order to use this annotation as a meta-annotation,
+	 * only use the {@link #type} attribute.
+	 * <p>
 	 * This attribute may <strong>not</strong> be used in conjunction with
 	 * {@link #type()}, but it may be used instead of {@link #type()}.
 	 * @return the class type of the bean to check