From 4883b8aa0362b71a62bc806843d9e14c988509c1 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sun, 26 Aug 2018 22:07:07 +0200 Subject: [PATCH] Polish JavaDoc for @Configuration --- .../context/annotation/Configuration.java | 73 ++++++++++--------- 1 file changed, 38 insertions(+), 35 deletions(-) diff --git a/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java b/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java index ef8c25f645..5bb1635433 100644 --- a/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java +++ b/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java @@ -46,7 +46,7 @@ import org.springframework.stereotype.Component; * *

Via {@code AnnotationConfigApplicationContext}

* - * {@code @Configuration} classes are typically bootstrapped using either + *

{@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,15 +59,17 @@ import org.springframework.stereotype.Component; * // use myBean ... * * - * See {@link AnnotationConfigApplicationContext} Javadoc for further details and see + *

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. * *

Via Spring {@code } XML

* *

As an alternative to registering {@code @Configuration} classes directly against an * {@code AnnotationConfigApplicationContext}, {@code @Configuration} classes may be * declared as normal {@code } definitions within Spring XML files: + * * 

  * <beans>
  *    <context:annotation-config/>
@@ -75,7 +77,7 @@ import org.springframework.stereotype.Component;
  * </beans>
  *
* - * In the example above, {@code } is required in order to + *

In the example above, {@code } is required in order to * enable {@link ConfigurationClassPostProcessor} and other annotation-related * post processors that facilitate handling {@code @Configuration} classes. * @@ -113,13 +115,13 @@ import org.springframework.stereotype.Component; * // various @Bean definitions ... * } * - * See the {@link ComponentScan @ComponentScan} javadoc for details. + *

See the {@link ComponentScan @ComponentScan} javadocs for details. * *

Working with externalized values

* *

Using the {@code Environment} API

* - * Externalized values may be looked up by injecting the Spring + *

Externalized values may be looked up by injecting the Spring * {@link org.springframework.core.env.Environment} into a {@code @Configuration} * class — for example, using the {@code @Autowired} annotation: * @@ -137,7 +139,7 @@ import org.springframework.stereotype.Component; * } * } * - * Properties resolved through the {@code Environment} reside in one or more "property + *

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 @@ import org.springframework.stereotype.Component; * } * } * - * See {@link org.springframework.core.env.Environment Environment} - * and {@link PropertySource @PropertySource} Javadoc for further details. + *

See the {@link org.springframework.core.env.Environment Environment} + * and {@link PropertySource @PropertySource} javadocs for further details. * *

Using the {@code @Value} annotation

* - * Externalized values may be 'wired into' {@code @Configuration} classes using - * the {@link Value @Value} annotation: + *

Externalized values may be injected {@code @Configuration} classes using the + * {@link Value @Value} annotation: * * 

  * @Configuration
@@ -176,13 +178,13 @@ import org.springframework.stereotype.Component;
  *     }
  * }
* - * This approach is most useful when using Spring's + *

This approach is most useful when using Spring's * {@link org.springframework.context.support.PropertySourcesPlaceholderConfigurer * PropertySourcesPlaceholderConfigurer}, usually enabled via XML with * {@code }. 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}. * *

Composing {@code @Configuration} classes

@@ -221,7 +223,7 @@ import org.springframework.stereotype.Component; * } * } * - * Now both {@code AppConfig} and the imported {@code DatabaseConfig} can be bootstrapped + *

Now both {@code AppConfig} and the imported {@code DatabaseConfig} can be bootstrapped * by registering only {@code AppConfig} against the Spring context: * * 

@@ -229,7 +231,7 @@ import org.springframework.stereotype.Component;
  *
  * 
With the {@code @Profile} annotation

  *
- * {@code @Configuration} classes may be marked with the {@link Profile @Profile} annotation to
+ * 
{@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 active:
  *
  * 
@@ -253,8 +255,8 @@ import org.springframework.stereotype.Component;
  *     }
  * }

  *
- * Alternatively, you may also declare profile conditions at the {@code @Bean} method level,
- * e.g. for alternative bean variants within the same configuration class:
+ * 
Alternatively, you may also declare profile conditions at the {@code @Bean} method level
+ * — for example, for alternative bean variants within the same configuration class:
  *
  * 
  * @Configuration
@@ -269,12 +271,12 @@ import org.springframework.stereotype.Component;
  *     public DataSource productionDatabase() { ... }
  * }

  *
- * See the {@link Profile @Profile} and {@link org.springframework.core.env.Environment}
+ * 
See the {@link Profile @Profile} and {@link org.springframework.core.env.Environment}
  * javadocs for further details.
  *
  * 
With Spring XML using the {@code @ImportResource} annotation

  *
- * As mentioned above, {@code @Configuration} classes may be declared as regular Spring
+ * 
As mentioned above, {@code @Configuration} classes may be declared as regular Spring
  * {@code } 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 @@ import org.springframework.stereotype.Component;
  *
  * 
With nested {@code @Configuration} classes

  *
- * {@code @Configuration} classes may be nested within one another as follows:
+ * 
{@code @Configuration} classes may be nested within one another as follows:
  *
  * 
  * @Configuration
@@ -318,11 +320,11 @@ import org.springframework.stereotype.Component;
  *     }
  * }

  *
- * When bootstrapping such an arrangement, only {@code AppConfig} need be registered
+ * 
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} will be registered automatically. 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.
  *
  * 
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 @@ import org.springframework.stereotype.Component;
  *
  * 
Testing support for {@code @Configuration} classes

  *
- * The Spring TestContext framework available in the {@code spring-test} module
+ * 
The Spring TestContext framework 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 @@ import org.springframework.stereotype.Component;
  *
  * 
Enabling built-in Spring features using {@code @Enable} annotations

  *
- * Spring features such as asynchronous method execution, scheduled task execution,
+ * 
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 @@ import org.springframework.stereotype.Component;
 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.
-	 * 
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.
+	 * 
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)
-- 
GitLab