From e1080f8b5f5dd300ff57b016ebc1854b835b3c51 Mon Sep 17 00:00:00 2001
From: Sam Brannen <sbrannen@pivotal.io>
Date: Thu, 4 Apr 2019 18:18:35 +0200
Subject: [PATCH] Polish Javadoc for @Autowired

---
 .../beans/factory/annotation/Autowired.java   | 29 ++++++++++++-------
 1 file changed, 19 insertions(+), 10 deletions(-)

diff --git a/spring-beans/src/main/java/org/springframework/beans/factory/annotation/Autowired.java b/spring-beans/src/main/java/org/springframework/beans/factory/annotation/Autowired.java
index a5471783e3..f19faa72cf 100644
--- a/spring-beans/src/main/java/org/springframework/beans/factory/annotation/Autowired.java
+++ b/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,10 +23,11 @@ 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.
  *
+ * <h3>Autowired Constructors</h3>
  * <p>Only one constructor (at max) of any given bean class may declare this annotation
  * with the 'required' parameter set to {@code true}, indicating <i>the</i> constructor
  * to autowire when used as a Spring bean. If multiple <i>non-required</i> constructors
@@ -37,28 +38,35 @@ import java.lang.annotation.Target;
  * 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.
  *
+ * <h3>Autowired Fields</h3>
  * <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.
  *
+ * <h3>Autowired Methods</h3>
  * <p>Config methods may have an arbitrary name and any number of arguments; each of
  * those arguments will be autowired with a matching bean in the Spring container.
  * 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.
  *
+ * <h3>Multiple Arguments and 'required' Semantics</h3>
  * <p>In the case of a multi-arg constructor or method, the 'required' parameter is
- * applicable to all arguments. Individual parameters may be declared as Java-8-style
+ * 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.
  *
- * <p>In case of a {@link java.util.Collection} or {@link java.util.Map} dependency type,
- * the container autowires all beans matching the declared value type. For such purposes,
- * the map keys must be declared as type String which will be resolved to the corresponding
- * bean names. Such a container-provided collection will be ordered, taking into account
- * {@link org.springframework.core.Ordered}/{@link org.springframework.core.annotation.Order}
- * values of the target components, otherwise following their registration order in the
- * container. Alternatively, a single matching target bean may also be a generally typed
+ * <h3>Autowiring Arrays, Collections, and Maps</h3>
+ * <p>In case of an array, {@link java.util.Collection}, or {@link java.util.Map}
+ * dependency type, the container autowires all beans matching the declared value
+ * type. For such purposes, the map keys must be declared as type {@code String}
+ * which will be resolved to the corresponding bean names. Such a container-provided
+ * collection will be ordered, taking into account
+ * {@link org.springframework.core.Ordered Ordered} and
+ * {@link org.springframework.core.annotation.Order @Order} values of the target
+ * components, otherwise following their registration order in the container.
+ * Alternatively, a single matching target bean may also be a generally typed
  * {@code Collection} or {@code Map} itself, getting injected as such.
  *
+ * <h3>Not supported in {@code BeanPostProcessor} or {@code BeanFactoryPostProcessor}</h3>
  * <p>Note that actual injection is performed through a
  * {@link org.springframework.beans.factory.config.BeanPostProcessor
  * BeanPostProcessor} which in turn means that you <em>cannot</em>
@@ -71,6 +79,7 @@ import java.lang.annotation.Target;
  *
  * @author Juergen Hoeller
  * @author Mark Fisher
+ * @author Sam Brannen
  * @since 2.5
  * @see AutowiredAnnotationBeanPostProcessor
  * @see Qualifier