Document meta-annotation support in the TCF

- Completed Javadoc for MetaAnnotationUtils.
- Added Javadoc notes to multiple annotations in the TCF, pointing out
  which annotations can be used as meta-annotations.

Issue: SPR-11109

spring-test/src/main/java/org/springframework/test/annotation/DirtiesContext.java

@@ -27,28 +27,30 @@ import java.lang.annotation.Target;
  * Test annotation which indicates that the
  * {@link org.springframework.context.ApplicationContext ApplicationContext}
  * associated with a test is <em>dirty</em> and should be closed:
+ *
  * <ul>
- * <li>after the current test, when declared at the method level</li>
- * <li>after each test method in the current test class, when declared at the
- * class level with class mode set to {@link ClassMode#AFTER_EACH_TEST_METHOD
- * AFTER_EACH_TEST_METHOD}</li>
- * <li>after the current test class, when declared at the class level with class
- * mode set to {@link ClassMode#AFTER_CLASS AFTER_CLASS}</li>
+ *   <li>after the current test, when declared at the method level</li>
+ *   <li>after each test method in the current test class, when declared at the
+ *   class level with class mode set to {@link ClassMode#AFTER_EACH_TEST_METHOD
+ *   AFTER_EACH_TEST_METHOD}</li>
+ *   <li>after the current test class, when declared at the class level with class
+ *   mode set to {@link ClassMode#AFTER_CLASS AFTER_CLASS}</li>
  * </ul>
- * <p>
- * Use this annotation if a test has modified the context &mdash; for example, by
- * replacing a bean definition or changing the state of a singleton bean.
+ *
+ * <p>Use this annotation if a test has modified the context &mdash; for example,
+ * by replacing a bean definition or changing the state of a singleton bean.
  * Subsequent tests will be supplied a new context.
- * </p>
- * <p>
- * {@code @DirtiesContext} may be used as a class-level and method-level
+ *
+ * <p>{@code @DirtiesContext} may be used as a class-level and method-level
  * annotation within the same class. In such scenarios, the
  * {@code ApplicationContext} will be marked as <em>dirty</em> after any
  * such annotated method as well as after the entire class. If the
  * {@link ClassMode} is set to {@link ClassMode#AFTER_EACH_TEST_METHOD
  * AFTER_EACH_TEST_METHOD}, the context will be marked dirty after each test
  * method in the class.
- * </p>
+ *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
  *
  * @author Sam Brannen
  * @author Rod Johnson

spring-test/src/main/java/org/springframework/test/annotation/IfProfileValue.java

@@ -63,6 +63,9 @@ import java.lang.annotation.Target;
  * }
  * </pre>
  *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ *
  * @author Rod Johnson
  * @author Sam Brannen
  * @since 2.0

spring-test/src/main/java/org/springframework/test/annotation/ProfileValueSourceConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2013 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.
@@ -24,12 +24,13 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * <p>
- * ProfileValueSourceConfiguration is a class-level annotation which is used to
- * specify what type of {@link ProfileValueSource} to use when retrieving
- * <em>profile values</em> configured via the {@link IfProfileValue
+ * <p>{@code ProfileValueSourceConfiguration} is a class-level annotation which
+ * is used to specify what type of {@link ProfileValueSource} to use when
+ * retrieving <em>profile values</em> configured via the {@link IfProfileValue
  * &#064;IfProfileValue} annotation.
- * </p>
+ *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
  *
  * @author Sam Brannen
  * @since 2.5

spring-test/src/main/java/org/springframework/test/annotation/Repeat.java

@@ -30,6 +30,9 @@ import static java.lang.annotation.RetentionPolicy.*;
  * test method itself as well as any <em>set up</em> or <em>tear down</em> of
  * the test fixture.
  *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ *
  * @author Rod Johnson
  * @author Sam Brannen
  * @since 2.0

spring-test/src/main/java/org/springframework/test/annotation/Rollback.java

@@ -29,6 +29,9 @@ import static java.lang.annotation.RetentionPolicy.*;
  * has completed. If {@code true}, the transaction will be rolled back;
  * otherwise, the transaction will be committed.
  *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ *
  * @author Sam Brannen
  * @since 2.5
  */

spring-test/src/main/java/org/springframework/test/annotation/Timed.java

@@ -34,6 +34,9 @@ import static java.lang.annotation.RetentionPolicy.*;
  * any {@link Repeat repetitions} of the test, and any <em>set up</em> or
  * <em>tear down</em> of the test fixture.
  *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ *
  * @author Rod Johnson
  * @author Sam Brannen
  * @since 2.0

spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java

@@ -29,6 +29,9 @@ import java.lang.annotation.Target;
  * an {@link org.springframework.context.ApplicationContext ApplicationContext}
  * for test classes.
  *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ *
  * @author Sam Brannen
  * @since 3.1
  * @see SmartContextLoader

spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java

@@ -64,6 +64,9 @@ import org.springframework.context.ConfigurableApplicationContext;
  * for further information regarding the configuration and semantics of
  * <em>annotated classes</em>.
  *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ *
  * @author Sam Brannen
  * @since 2.5
  * @see ContextHierarchy

spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java

@@ -131,6 +131,9 @@ import java.lang.annotation.Target;
  * )
  * public class ExtendedTests extends BaseTests {}</pre>
  *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ *
  * @author Sam Brannen
  * @since 3.2.2
  * @see ContextConfiguration

spring-test/src/main/java/org/springframework/test/context/MetaAnnotationUtils.java

@@ -20,6 +20,7 @@ import java.lang.annotation.Annotation;
 
 import org.springframework.core.annotation.AnnotatedElementUtils;
 import org.springframework.core.annotation.AnnotationAttributes;
+import org.springframework.core.annotation.AnnotationUtils;
 import org.springframework.core.style.ToStringCreator;
 import org.springframework.util.Assert;
 import org.springframework.util.ObjectUtils;
@@ -27,10 +28,26 @@ import org.springframework.util.ObjectUtils;
 import static org.springframework.core.annotation.AnnotationUtils.*;
 
 /**
- * TODO Document MetaAnnotationUtils.
+ * {@code MetaAnnotationUtils} is a collection of utility methods that complements
+ * support already available in {@link AnnotationUtils}.
+ *
+ * <p>Whereas {@code AnnotationUtils} only provides utilities for <em>getting</em>
+ * or <em>finding</em> an annotation, {@code MetaAnnotationUtils} provides
+ * additional support for determining the <em>root class</em> on which an
+ * annotation is declared, either directly or via a <em>composed annotation</em>.
+ * This additional information is encapsulated in an {@link AnnotationDescriptor}.
+ *
+ * <p>The additional information provided by an {@code AnnotationDescriptor} is
+ * required in the <em>Spring TestContext Framework</em> in order to be able to
+ * support class hierarchy traversals for <em>inherited</em> annotations such as
+ * {@link ContextConfiguration @ContextConfiguration},
+ * {@link TestExecutionListeners @TestExecutionListeners}, and
+ * {@link ActiveProfiles @ActiveProfiles}.
  *
  * @author Sam Brannen
  * @since 4.0
+ * @see AnnotationUtils
+ * @see AnnotationDescriptor
  */
 abstract class MetaAnnotationUtils {
 
@@ -39,13 +56,37 @@ abstract class MetaAnnotationUtils {
 	}
 
 	/**
-	 * TODO Document findAnnotationDescriptor().
+	 * Find the {@link AnnotationDescriptor} for the supplied {@code annotationType}
+	 * from the supplied {@link Class}, traversing its annotations and superclasses
+	 * if no annotation can be found on the given class itself.
+	 *
+	 * <p>This method explicitly handles class-level annotations which are not
+	 * declared as {@linkplain java.lang.annotation.Inherited inherited} <em>as
+	 * well as meta-annotations</em>.
+	 *
+	 * <p>The algorithm operates as follows:
+	 * <ol>
+	 *   <li>Search for a local declaration of the annotation on the given class
+	 *   and return a corresponding {@code AnnotationDescriptor} if found.
+	 *   <li>Search through all annotations that the given class declares,
+	 *   returning an {@code AnnotationDescriptor} for the first matching
+	 *   candidate, if any.
+	 *   <li>Proceed with introspection of the superclass hierarchy of the given
+	 *   class by returning to step #1 with the superclass as the class to look
+	 *   for annotations on.
+	 * </ol>
+	 *
+	 * <p>If the supplied {@code clazz} is an interface, only the interface
+	 * itself will be checked; the inheritance hierarchy for interfaces will not
+	 * be traversed.
 	 *
 	 * @param clazz the class to look for annotations on
 	 * @param annotationType the annotation class to look for, both locally and
 	 * as a meta-annotation
 	 * @return the corresponding annotation descriptor if the annotation was found;
 	 * otherwise {@code null}
+	 * @see AnnotationUtils#findAnnotationDeclaringClass(Class, Class)
+	 * @see #findAnnotationDescriptorForTypes(Class, Class...)
 	 */
 	public static <T extends Annotation> AnnotationDescriptor<T> findAnnotationDescriptor(Class<?> clazz,
 			Class<T> annotationType) {
@@ -76,13 +117,43 @@ abstract class MetaAnnotationUtils {
 	}
 
 	/**
-	 * TODO Document findAnnotationDescriptorForTypes().
+	 * Find the {@link UntypedAnnotationDescriptor} for the first {@link Class}
+	 * in the inheritance hierarchy of the specified {@code clazz} (including
+	 * the specified {@code clazz} itself) which declares at least one of the
+	 * specified {@code annotationTypes}, or {@code null} if none of the
+	 * specified annotation types could be found.
+	 * 
+	 * <p>This method traverses the annotations and superclasses of the specified
+	 * {@code clazz} if no annotation can be found on the given class itself.
+	 *
+	 * <p>This method explicitly handles class-level annotations which are not
+	 * declared as {@linkplain java.lang.annotation.Inherited inherited} <em>as
+	 * well as meta-annotations</em>.
+	 *
+	 * <p>The algorithm operates as follows:
+	 * <ol>
+	 *   <li>Search for a local declaration of one of the annotation types on
+	 *   the given class and return a corresponding {@code UntypedAnnotationDescriptor}
+	 *   if found.
+	 *   <li>Search through all annotations that the given class declares,
+	 *   returning an {@code UntypedAnnotationDescriptor} for the first matching
+	 *   candidate, if any.
+	 *   <li>Proceed with introspection of the superclass hierarchy of the given
+	 *   class by returning to step #1 with the superclass as the class to look
+	 *   for annotations on.
+	 * </ol>
+	 *
+	 * <p>If the supplied {@code clazz} is an interface, only the interface
+	 * itself will be checked; the inheritance hierarchy for interfaces will not
+	 * be traversed.
 	 *
 	 * @param clazz the class to look for annotations on
 	 * @param annotationTypes the types of annotations to look for, both locally
 	 * and as meta-annotations
 	 * @return the corresponding annotation descriptor if one of the annotations
 	 * was found; otherwise {@code null}
+	 * @see AnnotationUtils#findAnnotationDeclaringClassForTypes(java.util.List, Class)
+	 * @see #findAnnotationDescriptor(Class, Class)
 	 */
 	@SuppressWarnings("unchecked")
 	public static UntypedAnnotationDescriptor findAnnotationDescriptorForTypes(Class<?> clazz,
@@ -241,6 +312,14 @@ abstract class MetaAnnotationUtils {
 		}
 	}
 
+	/**
+	 * <em>Untyped</em> extension of {@code AnnotationDescriptor} that is used
+	 * to describe the declaration of one of several candidate annotation types
+	 * where the actual annotation type cannot be predetermined.
+	 *
+	 * @author Sam Brannen
+	 * @since 4.0
+	 */
 	public static class UntypedAnnotationDescriptor extends AnnotationDescriptor<Annotation> {
 
 		public UntypedAnnotationDescriptor(Class<?> declaringClass, Annotation annotation) {

spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java

@@ -31,6 +31,9 @@ import java.lang.annotation.Target;
  * <p>Typically, {@code @TestExecutionListeners} will be used in conjunction with
  * {@link ContextConfiguration @ContextConfiguration}.
  *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ *
  * @author Sam Brannen
  * @since 2.5
  * @see TestExecutionListener

spring-test/src/main/java/org/springframework/test/context/transaction/AfterTransaction.java

@@ -24,16 +24,17 @@ import static java.lang.annotation.ElementType.*;
 import static java.lang.annotation.RetentionPolicy.*;
 
 /**
- * <p>
- * Test annotation to indicate that the annotated {@code public void}
+ * <p>Test annotation to indicate that the annotated {@code public void}
  * method should be executed <em>after</em> a transaction is ended for test
  * methods configured to run within a transaction via the
  * {@code &#064;Transactional} annotation.
- * </p>
+ *
  * <p>
  * The {@code &#064;AfterTransaction} methods of superclasses will be
  * executed after those of the current class.
- * </p>
+ *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
  *
  * @author Sam Brannen
  * @since 2.5

spring-test/src/main/java/org/springframework/test/context/transaction/BeforeTransaction.java

@@ -24,17 +24,18 @@ import static java.lang.annotation.ElementType.*;
 import static java.lang.annotation.RetentionPolicy.*;
 
 /**
- * <p>
- * Test annotation to indicate that the annotated {@code public void}
+ * <p>Test annotation to indicate that the annotated {@code public void}
  * method should be executed <em>before</em> a transaction is started for test
  * methods configured to run within a transaction via the
  * {@code &#064;Transactional} annotation.
- * </p>
- * <p>
- * The {@code &#064;BeforeTransaction} methods of superclasses will be
+ *
+ * <p>The {@code &#064;BeforeTransaction} methods of superclasses will be
  * executed before those of the current class.
  * </p>
  *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ *
  * @author Sam Brannen
  * @since 2.5
  * @see org.springframework.transaction.annotation.Transactional

spring-test/src/main/java/org/springframework/test/context/transaction/TransactionConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2013 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.
@@ -27,6 +27,9 @@ import java.lang.annotation.Target;
  * {@code TransactionConfiguration} defines class-level metadata for configuring
  * transactional tests.
  *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ *
  * @author Sam Brannen
  * @since 2.5
  * @see TransactionalTestExecutionListener

spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java

@@ -38,6 +38,9 @@ import java.lang.annotation.Target;
  * {@link org.springframework.test.context.ContextConfiguration @ContextConfiguration},
  * either within a single test class or within a test class hierarchy.
  *
+ * <p>As of Spring Framework 4.0, this annotation may be used as a
+ * <em>meta-annotation</em> to create custom <em>composed annotations</em>.
+ *
  * @author Sam Brannen
  * @since 3.2
  * @see org.springframework.web.context.WebApplicationContext

spring-test/src/test/java/org/springframework/test/context/MetaAnnotationUtilsTests.java

@@ -36,6 +36,7 @@ import static org.springframework.test.context.MetaAnnotationUtils.*;
  *
  * @author Sam Brannen
  * @since 4.0
+ * @see OverriddenMetaAnnotationAttributesTests
  */
 public class MetaAnnotationUtilsTests {
 

spring-test/src/test/java/org/springframework/test/context/OverriddenMetaAnnotationAttributesTests.java

@@ -34,6 +34,7 @@ import static org.springframework.test.context.MetaAnnotationUtils.*;
  *
  * @author Sam Brannen
  * @since 4.0
+ * @see MetaAnnotationUtilsTests
  */
 public class OverriddenMetaAnnotationAttributesTests {