Polish Javadoc for MergedAnnotation support

See gh-21697

Author: sbrannen

spring-core/src/main/java/org/springframework/core/annotation/AbstractMergedAnnotation.java

@@ -199,7 +199,7 @@ private <T> T getRequiredAttributeValue(String attributeName, Class<T> type) {
 	 * Get the underlying attribute value.
 	 * @param attributeName the attribute name
 	 * @param type the type to return (see {@link MergedAnnotation} class
-	 * documentation for details).
+	 * documentation for details)
 	 * @return the attribute value or {@code null} if the value is not found and
 	 * is not required
 	 * @throws IllegalArgumentException if the source type is not compatible

spring-core/src/main/java/org/springframework/core/annotation/AnnotationFilter.java

@@ -35,7 +35,7 @@ public interface AnnotationFilter {
 
 	/**
 	 * {@link AnnotationFilter} that matches annotations in the
-	 * {@code java.*}/{@code javax.*} namespaces.
+	 * {@code java.*} and {@code javax.*} namespaces.
 	 */
 	AnnotationFilter JAVA = packages("java", "javax");
 
@@ -75,14 +75,14 @@ default boolean matches(Class<?> type) {
 
 	/**
 	 * Test if the given type name matches the filter.
-	 * @param typeName the annotation type to test
+	 * @param typeName the fully qualified class name of the annotation type to test
 	 * @return {@code true} if the annotation matches
 	 */
 	boolean matches(String typeName);
 
 
 	/**
-	 * Return a new {@link AnnotationFilter} that matches annotations in the
+	 * Create a new {@link AnnotationFilter} that matches annotations in the
 	 * specified packages.
 	 * @param packages the annotation packages that should match
 	 * @return a new {@link AnnotationFilter} instance

spring-core/src/main/java/org/springframework/core/annotation/AnnotationTypeMapping.java

@@ -42,6 +42,7 @@
  * the context of a root annotation type.
  *
  * @author Phillip Webb
+ * @author Sam Brannen
  * @since 5.2
  * @see AnnotationTypeMappings
  */
@@ -339,15 +340,15 @@ private void validateMirrorSet(MirrorSet mirrorSet) {
 	}
 
 	/**
-	 * Return the root mapping.
+	 * Get the root mapping.
 	 * @return the root mapping
 	 */
 	AnnotationTypeMapping getRoot() {
 		return this.root;
 	}
 
 	/**
-	 * Return the parent mapping or {@code null}.
+	 * Get the parent mapping or {@code null}.
 	 * @return the parent mapping
 	 */
 	@Nullable
@@ -356,23 +357,23 @@ AnnotationTypeMapping getParent() {
 	}
 
 	/**
-	 * Return the depth of this mapping.
+	 * Get the depth of this mapping.
 	 * @return the depth of the mapping
 	 */
 	int getDepth() {
 		return this.depth;
 	}
 
 	/**
-	 * Return the type of the mapped annotation.
+	 * Get the type of the mapped annotation.
 	 * @return the annotation type
 	 */
 	Class<? extends Annotation> getAnnotationType() {
 		return this.annotationType;
 	}
 
 	/**
-	 * Return the source annotation for this mapping. This will be the
+	 * Get the source annotation for this mapping. This will be the
 	 * meta-annotation, or {@code null} if this is the root mapping.
 	 * @return the source annotation of the mapping
 	 */
@@ -382,15 +383,15 @@ Annotation getAnnotation() {
 	}
 
 	/**
-	 * Return the annotation attributes for the mapping annotation type.
+	 * Get the annotation attributes for the mapping annotation type.
 	 * @return the attribute methods
 	 */
 	AttributeMethods getAttributes() {
 		return this.attributes;
 	}
 
 	/**
-	 * Return the related index of an alias mapped attribute, or {@code -1} if
+	 * Get the related index of an alias mapped attribute, or {@code -1} if
 	 * there is no mapping. The resulting value is the index of the attribute on
 	 * the root annotation that can be invoked in order to obtain the actual
 	 * value.
@@ -402,7 +403,7 @@ int getAliasMapping(int attributeIndex) {
 	}
 
 	/**
-	 * Return the related index of a convention mapped attribute, or {@code -1}
+	 * Get the related index of a convention mapped attribute, or {@code -1}
 	 * if there is no mapping. The resulting value is the index of the attribute
 	 * on the root annotation that can be invoked in order to obtain the actual
 	 * value.
@@ -414,7 +415,7 @@ int getConventionMapping(int attributeIndex) {
 	}
 
 	/**
-	 * Return a mapped attribute value from the most suitable
+	 * Get a mapped attribute value from the most suitable
 	 * {@link #getAnnotation() meta-annotation}. The resulting value is obtained
 	 * from the closest meta-annotation, taking into consideration both
 	 * convention and alias based mapping rules. For root mappings, this method
@@ -433,7 +434,7 @@ Object getMappedAnnotationValue(int attributeIndex) {
 	}
 
 	/**
-	 * Return if the specified value is equivalent to the default value of the
+	 * Determine if the specified value is equivalent to the default value of the
 	 * attribute at the given index.
 	 * @param attributeIndex the attribute index of the source attribute
 	 * @param value the value to check
@@ -449,7 +450,7 @@ boolean isEquivalentToDefaultValue(int attributeIndex, Object value,
 	}
 
 	/**
-	 * Return the mirror sets for this type mapping.
+	 * Get the mirror sets for this type mapping.
 	 * @return the mirrorSets the attribute mirror sets.
 	 */
 	MirrorSets getMirrorSets() {

spring-core/src/main/java/org/springframework/core/annotation/AnnotationTypeMappings.java

@@ -33,7 +33,7 @@
  * root {@link Annotation}.
  *
  * <p>Supports convention based merging of meta-annotations as well as implicit
- * and explicit {@link AliasFor @AliasFor} aliases. Also provide information
+ * and explicit {@link AliasFor @AliasFor} aliases. Also provides information
  * about mirrored attributes.
  *
  * <p>This class is designed to be cached so that meta-annotations only need to
@@ -136,17 +136,17 @@ private boolean isAlreadyMapped(AnnotationTypeMapping parent, Annotation metaAnn
 	}
 
 	/**
-	 * Return the total number of contained mappings.
+	 * Get the total number of contained mappings.
 	 * @return the total number of mappings
 	 */
 	int size() {
 		return this.mappings.size();
 	}
 
 	/**
-	 * Return an individual mapping from this instance. Index {@code 0} will
-	 * always be return the root mapping, higer indexes will return
-	 * meta-annotation mappings.
+	 * Get an individual mapping from this instance.
+	 * <p>Index {@code 0} will always return the root mapping; higher indexes
+	 * will return meta-annotation mappings.
 	 * @param index the index to return
 	 * @return the {@link AnnotationTypeMapping}
 	 * @throws IndexOutOfBoundsException if the index is out of range
@@ -158,7 +158,7 @@ AnnotationTypeMapping get(int index) {
 
 
 	/**
-	 * Return {@link AnnotationTypeMappings} for the specified annotation type.
+	 * Create {@link AnnotationTypeMappings} for the specified annotation type.
 	 * @param annotationType the source annotation type
 	 * @return type mappings for the annotation type
 	 */
@@ -167,7 +167,7 @@ static AnnotationTypeMappings forAnnotationType(Class<? extends Annotation> anno
 	}
 
 	/**
-	 * Return {@link AnnotationTypeMappings} for the specified annotation type.
+	 * Create {@link AnnotationTypeMappings} for the specified annotation type.
 	 * @param annotationType the source annotation type
 	 * @param annotationFilter the annotation filter used to limit which
 	 * annotations are considered

spring-core/src/main/java/org/springframework/core/annotation/AnnotationsProcessor.java

@@ -58,7 +58,7 @@ default R doWithAggregate(C context, int aggregateIndex) {
 	R doWithAnnotations(C context, int aggregateIndex, @Nullable Object source, Annotation[] annotations);
 
 	/**
-	 * Return the final result to be returned. By default this method returns
+	 * Get the final result to be returned. By default this method returns
 	 * the last process result.
 	 * @param result the last early exit result, or {@code null} if none
 	 * @return the final result to be returned to the caller

spring-core/src/main/java/org/springframework/core/annotation/AnnotationsScanner.java

@@ -35,7 +35,7 @@
 import org.springframework.util.ReflectionUtils;
 
 /**
- * Scanner to search for relevant annotations on the hierarchy of an
+ * Scanner to search for relevant annotations in the annotation hierarchy of an
  * {@link AnnotatedElement}.
  *
  * @author Phillip Webb

spring-core/src/main/java/org/springframework/core/annotation/AttributeMethods.java

@@ -89,7 +89,7 @@ private AttributeMethods(@Nullable Class<? extends Annotation> annotationType, M
 
 
 	/**
-	 * Return if this instance only contains only a single attribute named
+	 * Determine if this instance only contains only a single attribute named
 	 * {@code value}.
 	 * @return {@code true} if this is only a value attribute
 	 */
@@ -100,9 +100,8 @@ boolean isOnlyValueAttribute() {
 
 
 	/**
-	 * Returns {@code true} if values from the given annotation can be safely
-	 * accessed without causing any {@link TypeNotPresentException
-	 * TypeNotPresentExceptions}.
+	 * Determine if values from the given annotation can be safely accessed without
+	 * causing any {@link TypeNotPresentException TypeNotPresentExceptions}.
 	 * @param annotation the annotation to check
 	 * @return {@code true} if all values are present
 	 * @see #validate(Annotation)
@@ -123,7 +122,7 @@ boolean isValid(Annotation annotation) {
 	}
 
 	/**
-	 * Checks if values from the given annotation can be safely accessed without causing
+	 * Check if values from the given annotation can be safely accessed without causing
 	 * any {@link TypeNotPresentException TypeNotPresentExceptions}. In particular,
 	 * this method is designed to cover Google App Engine's late arrival of such
 	 * exceptions for {@code Class} values (instead of the more typical early
@@ -155,7 +154,7 @@ private void assertAnnotation(Annotation annotation) {
 	}
 
 	/**
-	 * Return the attribute with the specified name or {@code null} if no
+	 * Get the attribute with the specified name or {@code null} if no
 	 * matching attribute exists.
 	 * @param name the attribute name to find
 	 * @return the attribute method or {@code null}
@@ -167,7 +166,7 @@ Method get(String name) {
 	}
 
 	/**
-	 * Return the attribute at the specified index.
+	 * Get the attribute at the specified index.
 	 * @param index the index of the attribute to return
 	 * @return the attribute method
 	 * @throws IndexOutOfBoundsException if the index is out of range
@@ -178,7 +177,7 @@ Method get(int index) {
 	}
 
 	/**
-	 * Return {@code true} if the attribute at the specified index could throw a
+	 * Determine if the attribute at the specified index could throw a
 	 * {@link TypeNotPresentException} when accessed.
 	 * @param index the index of the attribute to check
 	 * @return {@code true} if the attribute can throw a
@@ -189,7 +188,7 @@ boolean canThrowTypeNotPresentException(int index) {
 	}
 
 	/**
-	 * Return the index of the attribute with the specified name, or {@code -1}
+	 * Get the index of the attribute with the specified name, or {@code -1}
 	 * if there is no attribute with the name.
 	 * @param name the name to find
 	 * @return the index of the attribute, or {@code -1}
@@ -204,8 +203,8 @@ int indexOf(String name) {
 	}
 
 	/**
-	 * Return the index of the specified attribute , or {@code -1} if the
-	 * attribute is not not in this collection.
+	 * Get the index of the specified attribute, or {@code -1} if the
+	 * attribute is not in this collection.
 	 * @param attribute the attribute to find
 	 * @return the index of the attribute, or {@code -1}
 	 */
@@ -219,34 +218,35 @@ int indexOf(Method attribute) {
 	}
 
 	/**
-	 * Return the number of attributes in this collection.
+	 * Get the number of attributes in this collection.
 	 * @return the number of attributes
 	 */
 	int size() {
 		return this.attributeMethods.length;
 	}
 
 	/**
-	 * Return if at least one of the attribute methods has a default value.
-	 * @return if there is at least one attribute method with a default value
+	 * Determine if at least one of the attribute methods has a default value.
+	 * @return {@code true} if there is at least one attribute method with a default value
 	 */
 	boolean hasDefaultValueMethod() {
 		return this.hasDefaultValueMethod;
 	}
 
 	/**
-	 * Return if at least on of the attribute methods is a nested annotation.
-	 * @return if there is at least one attribute method with a annotation type
+	 * Determine if at least one of the attribute methods is a nested annotation.
+	 * @return {@code true} if there is at least one attribute method with a nested
+	 * annotation type
 	 */
 	boolean hasNestedAnnotation() {
 		return this.hasNestedAnnotation;
 	}
 
 
 	/**
-	 * Return the attribute methods for the given annotation type.
+	 * Get the attribute methods for the given annotation type.
 	 * @param annotationType the annotation type
-	 * @return the attribute methods for the annotation
+	 * @return the attribute methods for the annotation type
 	 */
 	static AttributeMethods forAnnotationType(@Nullable Class<? extends Annotation> annotationType) {
 		if (annotationType == null) {
@@ -278,7 +278,7 @@ private static boolean isAttributeMethod(Method method) {
 	}
 
 	/**
-	 * Return a description for the given attribute method suitable to use in
+	 * Create a description for the given attribute method suitable to use in
 	 * exception messages and logs.
 	 * @param attribute the attribute to describe
 	 * @return a description of the attribute
@@ -291,7 +291,7 @@ static String describe(@Nullable Method attribute) {
 	}
 
 	/**
-	 * Return a description for the given attribute method suitable to use in
+	 * Create a description for the given attribute method suitable to use in
 	 * exception messages and logs.
 	 * @param annotationType the annotation type
 	 * @param attributeName the attribute name