Documentation notes for @bean overriding and bean name matching

Closes gh-32825

Author: jhoeller

framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc

@@ -153,17 +153,15 @@ Letting qualifier values select against target bean names, within the type-match
 candidates, does not require a `@Qualifier` annotation at the injection point.
 If there is no other resolution indicator (such as a qualifier or a primary marker),
 for a non-unique dependency situation, Spring matches the injection point name
-(that is, the field name or parameter name) against the target bean names and chooses the
-same-named candidate, if any.
+(that is, the field name or parameter name) against the target bean names and chooses
+the same-named candidate, if any (either by bean name or by associated alias).
 
 Since version 6.1, this requires the `-parameters` Java compiler flag to be present.
 ====
 
-That said, if you intend to express annotation-driven injection by name, do not
-primarily use `@Autowired`, even if it is capable of selecting by bean name among
-type-matching candidates. Instead, use the JSR-250 `@Resource` annotation, which is
-semantically defined to identify a specific target component by its unique name, with
-the declared type being irrelevant for the matching process. `@Autowired` has rather
+As an alternative for injection by name, consider the JSR-250 `@Resource` annotation
+which is semantically defined to identify a specific target component by its unique name,
+with the declared type being irrelevant for the matching process. `@Autowired` has rather
 different semantics: After selecting candidate beans by type, the specified `String`
 qualifier value is considered within those type-selected candidates only (for example,
 matching an `account` qualifier against beans marked with the same qualifier label).

framework-docs/modules/ROOT/pages/core/beans/definition.adoc

@@ -75,6 +75,31 @@ lead to concurrent access exceptions, inconsistent state in the bean container,
 
 
 
+[[beans-definition-overriding]]
+== Overriding Beans
+
+Bean overriding is happening when a bean is registered using an identifier that is
+already allocated. While bean overriding is possible, it makes the configuration harder
+to read and this feature will be deprecated in a future release.
+
+To disable bean overriding altogether, you can set the `allowBeanDefinitionOverriding`
+flag to `false` on the `ApplicationContext` before it is refreshed. In such setup, an
+exception is thrown if bean overriding is used.
+
+By default, the container logs every bean overriding at `INFO` level so that you can
+adapt your configuration accordingly. While not recommended, you can silence those logs
+by setting the `allowBeanDefinitionOverriding` flag to `true`.
+
+.Java-configuration
+****
+If you use Java Configuration, a corresponding `@Bean` method always silently overrides
+a scanned bean class with the same component name as long as the return type of the
+`@Bean` method matches that bean class. This simply means that the container will call
+the `@Bean` factory method in favor of any pre-declared constructor on the bean class.
+****
+
+
+
 [[beans-beanname]]
 == Naming Beans