Improve Javadoc for AutowiredAnnotationBeanPostProcessor

See gh-23263

Author: sbrannen

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

@@ -69,50 +69,60 @@
 import org.springframework.util.StringUtils;
 
 /**
- * {@link org.springframework.beans.factory.config.BeanPostProcessor} implementation
- * that autowires annotated fields, setter methods and arbitrary config methods.
- * Such members to be injected are detected through a Java 5 annotation: by default,
- * Spring's {@link Autowired @Autowired} and {@link Value @Value} annotations.
+ * {@link org.springframework.beans.factory.config.BeanPostProcessor BeanPostProcessor}
+ * implementation that autowires annotated fields, setter methods, and arbitrary
+ * config methods. Such members to be injected are detected through annotations:
+ * by default, Spring's {@link Autowired @Autowired} and {@link Value @Value}
+ * annotations.
  *
  * <p>Also supports JSR-330's {@link javax.inject.Inject @Inject} annotation,
  * if available, as a direct alternative to Spring's own {@code @Autowired}.
  *
- * <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
- * 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.
+ * <h3>Autowired Constructors</h3>
+ * <p>Only one constructor of any given bean class may declare this annotation with
+ * the 'required' attribute set to {@code true}, indicating <i>the</i> constructor
+ * to autowire when used as a Spring bean. Furthermore, if the 'required' attribute
+ * is set to {@code true}, only a single constructor may be annotated with
+ * {@code @Autowired}. If multiple <i>non-required</i> 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.
  *
+ * <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. Config methods do not have to be public.
  *
- * <p>Note: A default AutowiredAnnotationBeanPostProcessor will be registered
+ * <h3>Annotation Config vs. XML Config</h3>
+ * <p>A default {@code AutowiredAnnotationBeanPostProcessor} will be registered
  * by the "context:annotation-config" and "context:component-scan" XML tags.
  * Remove or turn off the default annotation configuration there if you intend
- * to specify a custom AutowiredAnnotationBeanPostProcessor bean definition.
+ * to specify a custom {@code AutowiredAnnotationBeanPostProcessor} bean definition.
+ *
  * <p><b>NOTE:</b> Annotation injection will be performed <i>before</i> XML injection;
  * thus the latter configuration will override the former for properties wired through
  * both approaches.
  *
+ * <h3>{@literal @}Lookup Methods</h3>
  * <p>In addition to regular injection points as discussed above, this post-processor
  * also handles Spring's {@link Lookup @Lookup} annotation which identifies lookup
  * methods to be replaced by the container at runtime. This is essentially a type-safe
- * version of {@code getBean(Class, args)} and {@code getBean(String, args)},
+ * version of {@code getBean(Class, args)} and {@code getBean(String, args)}.
  * See {@link Lookup @Lookup's javadoc} for details.
  *
  * @author Juergen Hoeller
  * @author Mark Fisher
  * @author Stephane Nicoll
  * @author Sebastien Deleuze
+ * @author Sam Brannen
  * @since 2.5
  * @see #setAutowiredAnnotationType
  * @see Autowired
@@ -142,9 +152,10 @@ public class AutowiredAnnotationBeanPostProcessor extends InstantiationAwareBean
 
 
 	/**
-	 * Create a new AutowiredAnnotationBeanPostProcessor
-	 * for Spring's standard {@link Autowired} annotation.
-	 * <p>Also supports JSR-330's {@link javax.inject.Inject} annotation, if available.
+	 * Create a new {@code AutowiredAnnotationBeanPostProcessor} for Spring's
+	 * standard {@link Autowired @Autowired} annotation.
+	 * <p>Also supports JSR-330's {@link javax.inject.Inject @Inject} annotation,
+	 * if available.
 	 */
 	@SuppressWarnings("unchecked")
 	public AutowiredAnnotationBeanPostProcessor() {