Improve documentation for @Autowired constructors

Prior to this commit, there was some ambiguity surrounding semantics
for @Autowired constructors and `required = true`, especially for
multiple @Autowired constructors.

This commit improves the documentation in the Javadoc for @Autowired as
well as in the reference manual.

Closes gh-23263

spring-beans/src/main/java/org/springframework/beans/factory/annotation/Autowired.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -23,19 +23,21 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Marks a constructor, field, setter method or config method as to be autowired by
+ * Marks a constructor, field, setter method, or config method as to be autowired by
  * Spring's dependency injection facilities. This is an alternative to the JSR-330
  * {@link javax.inject.Inject} annotation, adding required-vs-optional semantics.
  *
- * <p>Only one constructor (at max) of any given bean class may declare this annotation
+ * <p>Only one constructor of any given bean class may declare this annotation with
- * with the 'required' parameter set to {@code true}, indicating <i>the</i> constructor
+ * the 'required' attribute set to {@code true}, indicating <i>the</i> constructor
- * to autowire when used as a Spring bean. If multiple <i>non-required</i> constructors
+ * to autowire when used as a Spring bean. Furthermore, if the 'required' attribute
- * declare the annotation, they will be considered as candidates for autowiring.
+ * is set to {@code true}, only a single constructor may be annotated with
- * The constructor with the greatest number of dependencies that can be satisfied by
+ * {@code @Autowired}. If multiple <i>non-required</i> constructors declare the
- * matching beans in the Spring container will be chosen. If none of the candidates
+ * annotation, they will be considered as candidates for autowiring. The constructor
- * can be satisfied, then a primary/default constructor (if present) will be used.
+ * with the greatest number of dependencies that can be satisfied by matching beans
- * If a class only declares a single constructor to begin with, it will always be used,
+ * in the Spring container will be chosen. If none of the candidates can be satisfied,
- * even if not annotated. An annotated constructor does not have to be public.
+ * then a primary/default constructor (if present) will be used. If a class only
+ * declares a single constructor to begin with, it will always be used, even if not
+ * annotated. An annotated constructor does not have to be public.
  *
  * <p>Fields are injected right after construction of a bean, before any config methods
  * are invoked. Such a config field does not have to be public.
@@ -45,7 +47,7 @@ import java.lang.annotation.Target;
  * Bean property setter methods are effectively just a special case of such a general
  * config method. Such config methods do not have to be public.
  *
- * <p>In the case of a multi-arg constructor or method, the 'required' parameter is
+ * <p>In the case of a multi-arg constructor or method, the 'required' attribute is
  * applicable to all arguments. Individual parameters may be declared as Java-8-style
  * {@link java.util.Optional} or, as of Spring Framework 5.0, also as {@code @Nullable}
  * or a not-null parameter type in Kotlin, overriding the base required semantics.

src/docs/asciidoc/core/core-beans.adoc

@@ -4811,15 +4811,19 @@ e.g. declared as a single public constructor without an `@Autowired` annotation.
 
 [NOTE]
 ====
-Only one annotated constructor per class can be marked as required, but multiple
+Only one constructor of any given bean class may declare `@Autowired` with the `required`
-non-required constructors can be annotated. In that case, each is considered among
+attribute set to `true`, indicating _the_ constructor to autowire when used as a Spring
-the candidates and Spring uses the greediest constructor whose dependencies can be
+bean. Furthermore, if the `required` attribute is set to `true`, only a single
-satisfied -- that is, the constructor that has the largest number of arguments.
+constructor may be annotated with `@Autowired`. If multiple _non-required_ constructors
-The constructor resolution algorithm is the same as for non-annotated classes with
+declare the annotation, they will be considered as candidates for autowiring. The
-overloaded constructors, just narrowing the candidates to annotated constructors.
+constructor with the greatest number of dependencies that can be satisfied by matching
+beans in the Spring container will be chosen. If none of the candidates can be satisfied,
+then a primary/default constructor (if present) will be used. If a class only declares a
+single constructor to begin with, it will always be used, even if not annotated. An
+annotated constructor does not have to be public.
 
-The 'required' attribute of `@Autowired` is recommended over the `@Required` annotation
+The `required` attribute of `@Autowired` is recommended over the `@Required` annotation
-on setter methods. The 'required' attribute indicates that the property is not required
+on setter methods. The `required` attribute indicates that the property is not required
 for autowiring purposes. The property is ignored if it cannot be autowired. `@Required`,
 on the other hand, is stronger in that it enforces the property to be set by any means
 supported by the container. If no value is defined, a corresponding exception is raised.