Documentation notes for @bean overriding and bean name matching

See gh-31052
See gh-28122

Author: jhoeller

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

@@ -154,17 +154,19 @@ 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.
+As of 6.2, the container applies fast shortcut resolution for bean name matches,
+bypassing the full type matching algorithm when the parameter name matches the
+bean name and no type, qualifier or primary conditions override the match. It is
+therefore recommendable for your parameter names to match the target bean names.
 ====
 
-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

@@ -73,6 +73,8 @@ runtime (concurrently with live access to the factory) is not officially support
 lead to concurrent access exceptions, inconsistent state in the bean container, or both.
 ====
 
+
+
 [[beans-definition-overriding]]
 == Overriding Beans
 
@@ -81,15 +83,26 @@ already allocated. While bean overriding is possible, it makes the configuration
 to read and this feature will be deprecated in a future release.
 
 To disable bean overriding altogether, you can set the `allowBeanDefinitionOverriding`
-to `false` on the `ApplicationContext` before it is refreshed. In such setup, an
+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`.
 
-NOTE: We acknowledge that overriding beans in a test is convenient, and there is
-explicit support for this. For more details please refer to xref:testing/testcontext-framework/bean-overriding.adoc[this section].
+.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.
+****
+
+NOTE: We acknowledge that overriding beans in a test scenario is convenient,
+and there is explicit support for this as of Spring Framework 6.2. Please refer to
+xref:testing/testcontext-framework/bean-overriding.adoc[this section] for more details.
+
+
 
 [[beans-beanname]]
 == Naming Beans