Polish JavaDoc for @configuration

Author: sbrannen

spring-context/src/main/java/org/springframework/context/annotation/Configuration.java

@@ -46,7 +46,7 @@
  *
  * <h3>Via {@code AnnotationConfigApplicationContext}</h3>
  *
- * {@code @Configuration} classes are typically bootstrapped using either
+ * <p>{@code @Configuration} classes are typically bootstrapped using either
  * {@link AnnotationConfigApplicationContext} or its web-capable variant,
  * {@link org.springframework.web.context.support.AnnotationConfigWebApplicationContext
  * AnnotationConfigWebApplicationContext}. A simple example with the former follows:
@@ -59,23 +59,25 @@
  * // use myBean ...
  * </pre>
  *
- * See {@link AnnotationConfigApplicationContext} Javadoc for further details and see
+ * <p>See the {@link AnnotationConfigApplicationContext} javadocs for further details, and see
  * {@link org.springframework.web.context.support.AnnotationConfigWebApplicationContext
- * AnnotationConfigWebApplicationContext} for {@code web.xml} configuration instructions.
+ * AnnotationConfigWebApplicationContext} for web configuration instructions in a
+ * {@code Servlet} container.
  *
  * <h3>Via Spring {@code <beans>} XML</h3>
  *
  * <p>As an alternative to registering {@code @Configuration} classes directly against an
  * {@code AnnotationConfigApplicationContext}, {@code @Configuration} classes may be
  * declared as normal {@code <bean>} definitions within Spring XML files:
+ *
  * <pre class="code">
  * &lt;beans&gt;
  *    &lt;context:annotation-config/&gt;
  *    &lt;bean class="com.acme.AppConfig"/&gt;
  * &lt;/beans&gt;
  * </pre>
  *
- * In the example above, {@code <context:annotation-config/>} is required in order to
+ * <p>In the example above, {@code <context:annotation-config/>} is required in order to
  * enable {@link ConfigurationClassPostProcessor} and other annotation-related
  * post processors that facilitate handling {@code @Configuration} classes.
  *
@@ -113,13 +115,13 @@
  *     // various &#064;Bean definitions ...
  * }</pre>
  *
- * See the {@link ComponentScan @ComponentScan} javadoc for details.
+ * <p>See the {@link ComponentScan @ComponentScan} javadocs for details.
  *
  * <h2>Working with externalized values</h2>
  *
  * <h3>Using the {@code Environment} API</h3>
  *
- * Externalized values may be looked up by injecting the Spring
+ * <p>Externalized values may be looked up by injecting the Spring
  * {@link org.springframework.core.env.Environment} into a {@code @Configuration}
  * class &mdash; for example, using the {@code @Autowired} annotation:
  *
@@ -137,7 +139,7 @@
  *     }
  * }</pre>
  *
- * Properties resolved through the {@code Environment} reside in one or more "property
+ * <p>Properties resolved through the {@code Environment} reside in one or more "property
  * source" objects, and {@code @Configuration} classes may contribute property sources to
  * the {@code Environment} object using the {@link PropertySource @PropertySource}
  * annotation:
@@ -155,13 +157,13 @@
  *     }
  * }</pre>
  *
- * See {@link org.springframework.core.env.Environment Environment}
- * and {@link PropertySource @PropertySource} Javadoc for further details.
+ * <p>See the {@link org.springframework.core.env.Environment Environment}
+ * and {@link PropertySource @PropertySource} javadocs for further details.
  *
  * <h3>Using the {@code @Value} annotation</h3>
  *
- * Externalized values may be 'wired into' {@code @Configuration} classes using
- * the {@link Value @Value} annotation:
+ * <p>Externalized values may be injected {@code @Configuration} classes using the
+ * {@link Value @Value} annotation:
  *
  * <pre class="code">
  * &#064;Configuration
@@ -176,13 +178,13 @@
  *     }
  * }</pre>
  *
- * This approach is most useful when using Spring's
+ * <p>This approach is most useful when using Spring's
  * {@link org.springframework.context.support.PropertySourcesPlaceholderConfigurer
  * PropertySourcesPlaceholderConfigurer}, usually enabled via XML with
  * {@code <context:property-placeholder/>}.  See the section below on composing
  * {@code @Configuration} classes with Spring XML using {@code @ImportResource},
- * see {@link Value @Value} Javadoc, and see {@link Bean @Bean} Javadoc for details
- * on working with {@code BeanFactoryPostProcessor} types such as
+ * see the {@link Value @Value} javadocs, and see the {@link Bean @Bean} javadocs for
+ * details on working with {@code BeanFactoryPostProcessor} types such as
  * {@code PropertySourcesPlaceholderConfigurer}.
  *
  * <h2>Composing {@code @Configuration} classes</h2>
@@ -221,15 +223,15 @@
  *     }
  * }</pre>
  *
- * Now both {@code AppConfig} and the imported {@code DatabaseConfig} can be bootstrapped
+ * <p>Now both {@code AppConfig} and the imported {@code DatabaseConfig} can be bootstrapped
  * by registering only {@code AppConfig} against the Spring context:
  *
  * <pre class="code">
  * new AnnotationConfigApplicationContext(AppConfig.class);</pre>
  *
  * <h3>With the {@code @Profile} annotation</h3>
  *
- * {@code @Configuration} classes may be marked with the {@link Profile @Profile} annotation to
+ * <p>{@code @Configuration} classes may be marked with the {@link Profile @Profile} annotation to
  * indicate they should be processed only if a given profile or profiles are <em>active</em>:
  *
  * <pre class="code">
@@ -253,8 +255,8 @@
  *     }
  * }</pre>
  *
- * Alternatively, you may also declare profile conditions at the {@code @Bean} method level,
- * e.g. for alternative bean variants within the same configuration class:
+ * <p>Alternatively, you may also declare profile conditions at the {@code @Bean} method level
+ * &mdash; for example, for alternative bean variants within the same configuration class:
  *
  * <pre class="code">
  * &#064;Configuration
@@ -269,12 +271,12 @@
  *     public DataSource productionDatabase() { ... }
  * }</pre>
  *
- * See the {@link Profile @Profile} and {@link org.springframework.core.env.Environment}
+ * <p>See the {@link Profile @Profile} and {@link org.springframework.core.env.Environment}
  * javadocs for further details.
  *
  * <h3>With Spring XML using the {@code @ImportResource} annotation</h3>
  *
- * As mentioned above, {@code @Configuration} classes may be declared as regular Spring
+ * <p>As mentioned above, {@code @Configuration} classes may be declared as regular Spring
  * {@code <bean>} definitions within Spring XML files. It is also possible to
  * import Spring XML configuration files into {@code @Configuration} classes using
  * the {@link ImportResource @ImportResource} annotation. Bean definitions imported from
@@ -296,7 +298,7 @@
  *
  * <h3>With nested {@code @Configuration} classes</h3>
  *
- * {@code @Configuration} classes may be nested within one another as follows:
+ * <p>{@code @Configuration} classes may be nested within one another as follows:
  *
  * <pre class="code">
  * &#064;Configuration
@@ -318,11 +320,11 @@
  *     }
  * }</pre>
  *
- * When bootstrapping such an arrangement, only {@code AppConfig} need be registered
+ * <p>When bootstrapping such an arrangement, only {@code AppConfig} need be registered
  * against the application context. By virtue of being a nested {@code @Configuration}
  * class, {@code DatabaseConfig} <em>will be registered automatically</em>. This avoids
  * the need to use an {@code @Import} annotation when the relationship between
- * {@code AppConfig} {@code DatabaseConfig} is already implicitly clear.
+ * {@code AppConfig} and {@code DatabaseConfig} is already implicitly clear.
  *
  * <p>Note also that nested {@code @Configuration} classes can be used to good effect
  * with the {@code @Profile} annotation to provide two options of the same bean to the
@@ -338,7 +340,7 @@
  *
  * <h2>Testing support for {@code @Configuration} classes</h2>
  *
- * The Spring <em>TestContext framework</em> available in the {@code spring-test} module
+ * <p>The Spring <em>TestContext framework</em> available in the {@code spring-test} module
  * provides the {@code @ContextConfiguration} annotation which can accept an array of
  * {@code @Configuration} {@code Class} objects:
  *
@@ -363,10 +365,10 @@
  *
  * <h2>Enabling built-in Spring features using {@code @Enable} annotations</h2>
  *
- * Spring features such as asynchronous method execution, scheduled task execution,
+ * <p>Spring features such as asynchronous method execution, scheduled task execution,
  * annotation driven transaction management, and even Spring MVC can be enabled and
- * configured from {@code @Configuration}
- * classes using their respective "{@code @Enable}" annotations. See
+ * configured from {@code @Configuration} classes using their respective "{@code @Enable}"
+ * annotations. See
  * {@link org.springframework.scheduling.annotation.EnableAsync @EnableAsync},
  * {@link org.springframework.scheduling.annotation.EnableScheduling @EnableScheduling},
  * {@link org.springframework.transaction.annotation.EnableTransactionManagement @EnableTransactionManagement},
@@ -409,14 +411,15 @@
 public @interface Configuration {
 
 	/**
-	 * Explicitly specify the name of the Spring bean definition associated
-	 * with this Configuration class. If left unspecified (the common case),
-	 * a bean name will be automatically generated.
-	 * <p>The custom name applies only if the Configuration class is picked up via
-	 * component scanning or supplied directly to a {@link AnnotationConfigApplicationContext}.
-	 * If the Configuration class is registered as a traditional XML bean definition,
-	 * the name/id of the bean element will take precedence.
-	 * @return the suggested component name, if any (or empty String otherwise)
+	 * Explicitly specify the name of the Spring bean definition associated with the
+	 * {@code @Configuration} class. If left unspecified (the common case), a bean
+	 * name will be automatically generated.
+	 * <p>The custom name applies only if the {@code @Configuration} class is picked
+	 * up via component scanning or supplied directly to an
+	 * {@link AnnotationConfigApplicationContext}. If the {@code @Configuration} class
+	 * is registered as a traditional XML bean definition, the name/id of the bean
+	 * element will take precedence.
+	 * @return the explicit component name, if any (or empty String otherwise)
 	 * @see org.springframework.beans.factory.support.DefaultBeanNameGenerator
 	 */
 	@AliasFor(annotation = Component.class)