Document need for $ separator when auto-config is nested

Closes spring-projectsgh-44298

Author: wilkinsona

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2024 the original author or authors.
+ * Copyright 2012-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.
@@ -38,8 +38,9 @@
  * {@link Configuration#proxyBeanMethods() proxyBeanMethods} is always {@code false}. They
  * are located using {@link ImportCandidates}.
  * <p>
- * Generally auto-configuration classes are marked as {@link Conditional @Conditional}
- * (most often using {@link ConditionalOnClass @ConditionalOnClass} and
+ * Generally, auto-configuration classes are top-level classes that are marked as
+ * {@link Conditional @Conditional} (most often using
+ * {@link ConditionalOnClass @ConditionalOnClass} and
  * {@link ConditionalOnMissingBean @ConditionalOnMissingBean} annotations).
  *
  * @author Moritz Halbritter
@@ -76,28 +77,34 @@
 	String value() default "";
 
 	/**
-	 * The auto-configure classes that should have not yet been applied.
+	 * The auto-configuration classes that should have not yet been applied.
 	 * @return the classes
 	 */
 	@AliasFor(annotation = AutoConfigureBefore.class, attribute = "value")
 	Class<?>[] before() default {};
 
 	/**
-	 * The names of the auto-configure classes that should have not yet been applied.
+	 * The names of the auto-configuration classes that should have not yet been applied.
+	 * In the unusual case that an auto-configuration class is not a top-level class, its
+	 * name should use {@code $} to separate it from its containing class, for example
+	 * {@code com.example.Outer$NestedAutoConfiguration}.
 	 * @return the class names
 	 */
 	@AliasFor(annotation = AutoConfigureBefore.class, attribute = "name")
 	String[] beforeName() default {};
 
 	/**
-	 * The auto-configure classes that should have already been applied.
+	 * The auto-configuration classes that should have already been applied.
 	 * @return the classes
 	 */
 	@AliasFor(annotation = AutoConfigureAfter.class, attribute = "value")
 	Class<?>[] after() default {};
 
 	/**
-	 * The names of the auto-configure classes that should have already been applied.
+	 * The names of the auto-configuration classes that should have already been applied.
+	 * In the unusual case that an auto-configuration class is not a top-level class, its
+	 * class name should use {@code $} to separate it from its containing class, for
+	 * example {@code com.example.Outer$NestedAutoConfiguration}.
 	 * @return the class names
 	 */
 	@AliasFor(annotation = AutoConfigureAfter.class, attribute = "name")

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-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.
@@ -44,14 +44,16 @@
 public @interface AutoConfigureAfter {
 
 	/**
-	 * The auto-configure classes that should have already been applied.
+	 * The auto-configuration classes that should have already been applied.
 	 * @return the classes
 	 */
 	Class<?>[] value() default {};
 
 	/**
-	 * The names of the auto-configure classes that should have already been applied.
-	 * @return the class names
+	 * The names of the auto-configuration classes that should have already been applied.
+	 * In the unusual case that an auto-configuration class is not a top-level class, its
+	 * class name should use {@code $} to separate it from its containing class, for
+	 * example {@code com.example.Outer$NestedAutoConfiguration}.
 	 * @since 1.2.2
 	 */
 	String[] name() default {};

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-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.
@@ -50,7 +50,10 @@
 	Class<?>[] value() default {};
 
 	/**
-	 * The names of the auto-configure classes that should have not yet been applied.
+	 * The names of the auto-configuration classes that should have not yet been applied.
+	 * In the unusual case that an auto-configuration class is not a top-level class, its
+	 * class name should use {@code $} to separate it from its containing class, for
+	 * example {@code com.example.Outer$NestedAutoConfiguration}.
 	 * @return the class names
 	 * @since 1.2.2
 	 */

spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/features/developing-auto-configuration.adoc

@@ -36,6 +36,8 @@ com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration
 
 TIP: You can add comments to the imports file using the `#` character.
 
+TIP:  In the unusual case that an auto-configuration class is not a top-level class, its class name should use `$` to separate it from its containing class, for example `com.example.Outer$NestedAutoConfiguration`.
+
 NOTE: Auto-configurations must be loaded _only_ by being named in the imports file.
 Make sure that they are defined in a specific package space and that they are never the target of component scanning.
 Furthermore, auto-configuration classes should not enable component scanning to find additional components.