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 standard 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}, overriding the base required semantics.
  *

src/asciidoc/core-beans.adoc

@@ -4530,16 +4530,22 @@ indicating __required__ dependencies. This behavior can be changed as demonstrat
 
 [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 the
+attribute set to `true`, indicating _the_ constructor to autowire when used as a Spring
-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
+declare the annotation, they will be considered as candidates for autowiring. The
+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
-The __required__ attribute indicates that the property is not required for autowiring
+on setter methods. The `required` attribute indicates that the property is not required
-purposes, the property is ignored if it cannot be autowired. `@Required`, on the other
+for autowiring purposes. The property is ignored if it cannot be autowired. `@Required`,
-hand, is stronger in that it enforces the property that was set by any means supported
+on the other hand, is stronger in that it enforces the property to be set by any means
-by the container. If no value is injected, a corresponding exception is raised.
+supported by the container. If no value is defined, a corresponding exception is raised.
 ====
 
 Alternatively, you may express the non-required nature of a particular dependency