Revise contribution

See gh-35491

framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc

@@ -323,11 +323,29 @@ sure that they are 'opened' (that is, that they use an `opens` declaration inste
 `exports` declaration in your `module-info` descriptor).
 ====
 
-==== Property placeholders and Ant-style patterns
+Furthermore, the `AutowiredAnnotationBeanPostProcessor` and
+`CommonAnnotationBeanPostProcessor` are both implicitly included when you use the
+`<context:component-scan>` element. That means that the two components are autodetected
+and wired together -- all without any bean configuration metadata provided in XML.
+
+NOTE: You can disable the registration of `AutowiredAnnotationBeanPostProcessor` and
+`CommonAnnotationBeanPostProcessor` by including the `annotation-config` attribute
+with a value of `false`.
+
+
+[[beans-scanning-placeholders-and-patterns]]
+=== Property Placeholders and Ant-style Patterns
+
+The `basePackages` and `value` attributes in `@ComponentScan` support `${...}` property
+placeholders which are resolved against the `Environment` as well as Ant-style package
+patterns such as `"org.example.+++**+++"`.
+
+In addition, multiple packages or patterns may be specified, either separately or within
+a single String — for example, `{"org.example.config", "org.example.service.+++**+++"}`
+or `"org.example.config, org.example.service.+++**+++"`.
 
-`@ComponentScan(basePackages)` supports `${…}` property placeholders resolved
-against the `Environment` and Ant-style package patterns such as `com.example.**`.
-Multiple packages and/or patterns may be specified.
+The following example specifies the `app.scan.packages` property placeholder for the
+implicit `value` attribute in `@ComponentScan`.
 
 [tabs]
 ======
@@ -336,41 +354,36 @@ Java::
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
 @Configuration
-@ComponentScan(basePackages = "${app.scan.packages}")
+@ComponentScan("${app.scan.packages}") // <1>
 public class AppConfig {
 	// ...
 }
 ----
+<1> `app.scan.packages` property placeholder to be resolved against the `Environment`
 
 Kotlin::
 +
 [source,kotlin,indent=0,subs="verbatim,quotes"]
 ----
 @Configuration
-@ComponentScan(basePackages = ["\${app.scan.packages}"])
+@ComponentScan(["\${app.scan.packages}"]) // <1>
 class AppConfig {
 	// ...
 }
 ----
+<1> `app.scan.packages` property placeholder to be resolved against the `Environment`
 ======
 
+The following listing represents a properties file which defines the `app.scan.packages`
+property. In the preceding example, it is assumed that this properties file has been
+registered with the `Environment` – for example, via `@PropertySource` or a similar
+mechanism.
+
 [source,properties,indent=0,subs="verbatim,quotes"]
 ----
-app.scan.packages=com.example.**,org.acme.*
+app.scan.packages=org.example.config, org.example.service.**
 ----
 
-NOTE: Ant-style patterns do not apply to `basePackageClasses`, which accepts concrete
-classes and derives packages from those classes.
-
-Furthermore, the `AutowiredAnnotationBeanPostProcessor` and
-`CommonAnnotationBeanPostProcessor` are both implicitly included when you use the
-component-scan element. That means that the two components are autodetected and
-wired together -- all without any bean configuration metadata provided in XML.
-
-NOTE: You can disable the registration of `AutowiredAnnotationBeanPostProcessor` and
-`CommonAnnotationBeanPostProcessor` by including the `annotation-config` attribute
-with a value of `false`.
-
 
 [[beans-scanning-filters]]
 == Using Filters to Customize Scanning

spring-context/src/main/java/org/springframework/context/annotation/ComponentScan.java

@@ -74,12 +74,8 @@ public @interface ComponentScan {
 	/**
 	 * Alias for {@link #basePackages}.
 	 * <p>Allows for more concise annotation declarations if no other attributes
-	 * are needed &mdash; for example, {@code @ComponentScan("org.my.pkg")}
-	 * instead of {@code @ComponentScan(basePackages = "org.my.pkg")}.
-	 * <p>This attribute has the same semantics as {@link #basePackages}, including
-	 * support for {@code ${...}} placeholders (resolved against the
-	 * {@link org.springframework.core.env.Environment Environment}) and
-	 * Ant-style package patterns (for example, {@code com.example.**}).
+	 * are needed &mdash; for example, {@code @ComponentScan("org.example")}
+	 * instead of {@code @ComponentScan(basePackages = "org.example")}.
 	 */
 	@AliasFor("basePackages")
 	String[] value() default {};
@@ -88,15 +84,16 @@ public @interface ComponentScan {
 	 * Base packages to scan for annotated components.
 	 * <p>{@link #value} is an alias for (and mutually exclusive with) this
 	 * attribute.
+	 * <p>Supports {@code ${...}} placeholders which are resolved against the
+	 * {@link org.springframework.core.env.Environment Environment} as well as
+	 * Ant-style package patterns &mdash; for example, {@code "org.example.**"}.
+	 * <p>Multiple packages or patterns may be specified, either separately or
+	 * within a single {@code String} &mdash; for example,
+	 * {@code {"org.example.config", "org.example.service.**"}} or
+	 * {@code "org.example.config, org.example.service.**"}.
 	 * <p>Use {@link #basePackageClasses} for a type-safe alternative to
 	 * String-based package names.
-	 * <p>Supports {@code ${...}} placeholders resolved against the
-	 * {@link org.springframework.core.env.Environment Environment} as well as
-	 * Ant-style package patterns (for example, {@code com.example.**}).
-	 * Multiple packages and/or patterns may be specified.
-	 * <p><strong>Note:</strong> Ant-style patterns are <em>not</em> applicable to
-	 * {@link #basePackageClasses()}, which accepts concrete classes for type-safe
-	 * package selection.
+	 * @see org.springframework.context.ConfigurableApplicationContext#CONFIG_LOCATION_DELIMITERS
 	 */
 	@AliasFor("value")
 	String[] basePackages() default {};
@@ -106,8 +103,6 @@ public @interface ComponentScan {
 	 * to scan for annotated components. The package of each class specified will be scanned.
 	 * <p>Consider creating a special no-op marker class or interface in each package
 	 * that serves no purpose other than being referenced by this attribute.
-	 * <p><strong>Note:</strong> Ant-style package patterns do not apply here; this
-	 * attribute accepts concrete classes only and derives packages from those classes.
 	 */
 	Class<?>[] basePackageClasses() default {};