Polish Javadoc for @EnableAsync

spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java

@@ -30,8 +30,12 @@ import org.springframework.core.Ordered;
 
 /**
  * Enables Spring's asynchronous method execution capability, similar to functionality
- * found in Spring's {@code <task:*>} XML namespace. To be used on @{@link Configuration}
- * classes as follows:
+ * found in Spring's {@code <task:*>} XML namespace.
+ *
+ * <p>To be used on @{@link Configuration} classes as follows, where {@code MyAsyncBean}
+ * is a user-defined type with one or more methods annotated with either Spring's
+ * {@code @Async} annotation, the EJB 3.1 {@code @javax.ejb.Asynchronous} annotation,
+ * or any custom annotation specified via the {@link #annotation} attribute.
  *
  * <pre class="code">
  * &#064;Configuration
@@ -43,17 +47,15 @@ import org.springframework.core.Ordered;
  *     }
  * }</pre>
  *
- * where {@code MyAsyncBean} is a user-defined type with one or methods annotated
- * with @{@link Async} (or any custom annotation specified by the {@link #annotation()}
- * attribute).
  *
- * <p>The {@link #mode()} attribute controls how advice is applied; if the mode is
+ * <p>The {@link #mode} attribute controls how advice is applied; if the mode is
  * {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior
  * of the proxying.
  *
  * <p>Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then
- * the {@link #proxyTargetClass()} attribute is obsolete. Note also that in this case the
- * {@code spring-aspects} module JAR must be present on the classpath.
+ * the value of the {@link #proxyTargetClass} attribute will be ignored. Note also
+ * that in this case the {@code spring-aspects} module JAR must be present on the
+ * classpath.
  *
  * <p>By default, a {@link org.springframework.core.task.SimpleAsyncTaskExecutor
  * SimpleAsyncTaskExecutor} will be used to process async method invocations. Besides,
@@ -64,9 +66,9 @@ import org.springframework.core.Ordered;
  * provide:
  * <ul>
  * <li>your own {@link java.util.concurrent.Executor Executor} through the
- * {@link AsyncConfigurer#getAsyncExecutor() getAsyncExecutor()} method, and</li>
+ * {@link AsyncConfigurer#getAsyncExecutor getAsyncExecutor()} method, and</li>
  * <li>your own {@link org.springframework.aop.interceptor.AsyncUncaughtExceptionHandler
- * AsyncUncaughtExceptionHandler} through the {@link AsyncConfigurer#getAsyncUncaughtExceptionHandler()
+ * AsyncUncaughtExceptionHandler} through the {@link AsyncConfigurer#getAsyncUncaughtExceptionHandler
  * getAsyncUncaughtExceptionHandler()}
  * method.</li>
  * </ul>
@@ -102,6 +104,12 @@ import org.springframework.core.Ordered;
  * keep the default settings. Consider also extending from {@link AsyncConfigurerSupport}
  * when possible.
  *
+ * <p>Note: In the above example the {@code ThreadPoolTaskExecutor} is not a fully managed
+ * Spring bean. Add the {@code @Bean} annotation to the {@code getAsyncExecutor()} method
+ * if you want a fully managed bean. In such circumstances it is no longer necessary to
+ * manually call the {@code executor.initialize()} method as this will be invoked
+ * automatically when the bean is initialized.
+ *
  * <p>For reference, the example above can be compared to the following Spring XML
  * configuration:
  * <pre class="code">
@@ -113,19 +121,16 @@ import org.springframework.core.Ordered;
  *     <bean id="exceptionHandler" class="com.foo.MyAsyncUncaughtExceptionHandler"/>
  * </beans>
  * }</pre>
- * the examples are equivalent except the setting of the <em>thread name prefix</em> of the
- * Executor; this is because the the {@code task:} namespace {@code executor} element does
- * not expose such an attribute. This demonstrates how the code-based approach allows for
- * maximum configurability through direct access to actual componentry.
  *
- * <p>Note: In the above example the {@code ThreadPoolTaskExecutor} is not a fully managed
- * Spring Bean. Add the {@code @Bean} annotation to the {@code getAsyncExecutor()} method
- * if you want a fully managed bean. In such circumstances it is no longer necessary to
- * manually call the {@code executor.initialize()} method as this will be invoked
- * automatically when the bean is initialized.
+ * The above XML-based and JavaConfig-based examples are equivalent except for the
+ * setting of the <em>thread name prefix</em> of the {@code Executor}; this is because
+ * the {@code <task:executor>} element does not expose such an attribute. This
+ * demonstrates how the JavaConfig-based approach allows for maximum configurability
+ * through direct access to actual componentry.
  *
  * @author Chris Beams
  * @author Stephane Nicoll
+ * @author Sam Brannen
  * @since 3.1
  * @see Async
  * @see AsyncConfigurer
@@ -138,39 +143,42 @@ import org.springframework.core.Ordered;
 public @interface EnableAsync {
 
 	/**
-	 * Indicate the 'async' annotation type to be detected at either class or
-	 * method level. By default, both the {@link Async} annotation and the
-	 * EJB 3.1 {@code javax.ejb.Asynchronous} annotation will be detected.
-	 * <p>This setter property exists so that developers can provide their
-	 * own (non-Spring-specific) annotation type to indicate that a method
-	 * (or all methods of a given class) should be invoked asynchronously.
+	 * Indicate the 'async' annotation type to be detected at either class
+	 * or method level.
+	 * <p>By default, both Spring's @{@link Async} annotation and the EJB
+	 * 3.1 {@code @javax.ejb.Asynchronous} annotation will be detected.
+	 * <p>This attribute exists so that developers can provide their own
+	 * custom annotation type to indicate that a method (or all methods of
+	 * a given class) should be invoked asynchronously.
 	 */
 	Class<? extends Annotation> annotation() default Annotation.class;
 
 	/**
 	 * Indicate whether subclass-based (CGLIB) proxies are to be created as opposed
-	 * to standard Java interface-based proxies. The default is {@code false}. <strong>
-	 * Applicable only if {@link #mode()} is set to {@link AdviceMode#PROXY}</strong>.
+	 * to standard Java interface-based proxies.
+	 * <p><strong>Applicable only if the {@link #mode} is set to {@link AdviceMode#PROXY}</strong>.
+	 * <p>The default is {@code false}.
 	 * <p>Note that setting this attribute to {@code true} will affect <em>all</em>
 	 * Spring-managed beans requiring proxying, not just those marked with {@code @Async}.
 	 * For example, other beans marked with Spring's {@code @Transactional} annotation
 	 * will be upgraded to subclass proxying at the same time. This approach has no
 	 * negative impact in practice unless one is explicitly expecting one type of proxy
-	 * vs another, e.g. in tests.
+	 * vs. another &mdash; for example, in tests.
 	 */
 	boolean proxyTargetClass() default false;
 
 	/**
-	 * Indicate how async advice should be applied. The default is
-	 * {@link AdviceMode#PROXY}.
+	 * Indicate how async advice should be applied.
+	 * <p>The default is {@link AdviceMode#PROXY}.
 	 * @see AdviceMode
 	 */
 	AdviceMode mode() default AdviceMode.PROXY;
 
 	/**
 	 * Indicate the order in which the
-	 * {@link org.springframework.scheduling.annotation.AsyncAnnotationBeanPostProcessor}
-	 * should be applied. The default is {@link Ordered#LOWEST_PRECEDENCE} in order to run
+	 * {@link org.springframework.scheduling.annotation.AsyncAnnotationBeanPostProcessor
+	 * AsyncAnnotationBeanPostProcessor} should be applied.
+	 * <p>The default is {@link Ordered#LOWEST_PRECEDENCE} in order to run
 	 * after all other post-processors, so that it can add an advisor to
 	 * existing proxies rather than double-proxy.
 	 */