Polish Javadoc for MergedAnnotation support

See gh-21697

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

@@ -199,7 +199,7 @@ abstract class AbstractMergedAnnotation<A extends Annotation> implements MergedA
 	 * 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 @@ public interface AnnotationFilter {
 
 	/**
 	 * 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 @@ import org.springframework.util.StringUtils;
  * the context of a root annotation type.
  *
  * @author Phillip Webb
+ * @author Sam Brannen
  * @since 5.2
  * @see AnnotationTypeMappings
  */
@@ -339,7 +340,7 @@ final class AnnotationTypeMapping {
 	}
 
 	/**
-	 * Return the root mapping.
+	 * Get the root mapping.
 	 * @return the root mapping
 	 */
 	AnnotationTypeMapping getRoot() {
@@ -347,7 +348,7 @@ final class AnnotationTypeMapping {
 	}
 
 	/**
-	 * Return the parent mapping or {@code null}.
+	 * Get the parent mapping or {@code null}.
 	 * @return the parent mapping
 	 */
 	@Nullable
@@ -356,7 +357,7 @@ final class AnnotationTypeMapping {
 	}
 
 	/**
-	 * Return the depth of this mapping.
+	 * Get the depth of this mapping.
 	 * @return the depth of the mapping
 	 */
 	int getDepth() {
@@ -364,7 +365,7 @@ final class AnnotationTypeMapping {
 	}
 
 	/**
-	 * Return the type of the mapped annotation.
+	 * Get the type of the mapped annotation.
 	 * @return the annotation type
 	 */
 	Class<? extends Annotation> getAnnotationType() {
@@ -372,7 +373,7 @@ final class AnnotationTypeMapping {
 	}
 
 	/**
-	 * 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,7 +383,7 @@ final class AnnotationTypeMapping {
 	}
 
 	/**
-	 * Return the annotation attributes for the mapping annotation type.
+	 * Get the annotation attributes for the mapping annotation type.
 	 * @return the attribute methods
 	 */
 	AttributeMethods getAttributes() {
@@ -390,7 +391,7 @@ final class AnnotationTypeMapping {
 	}
 
 	/**
-	 * 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 @@ final class AnnotationTypeMapping {
 	}
 
 	/**
-	 * 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 @@ final class AnnotationTypeMapping {
 	}
 
 	/**
-	 * 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 @@ final class AnnotationTypeMapping {
 	}
 
 	/**
-	 * 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 @@ final class AnnotationTypeMapping {
 	}
 
 	/**
-	 * 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 @@ import org.springframework.util.ConcurrentReferenceHashMap;
  * 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,7 +136,7 @@ final class AnnotationTypeMappings {
 	}
 
 	/**
-	 * Return the total number of contained mappings.
+	 * Get the total number of contained mappings.
 	 * @return the total number of mappings
 	 */
 	int size() {
@@ -144,9 +144,9 @@ final class AnnotationTypeMappings {
 	}
 
 	/**
-	 * 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 @@ final class AnnotationTypeMappings {
 
 
 	/**
-	 * 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 @@ final class AnnotationTypeMappings {
 	}
 
 	/**
-	 * 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 @@ interface AnnotationsProcessor<C, R> {
 	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.ObjectUtils;
 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 @@ final class AttributeMethods {
 
 
 	/**
-	 * 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 @@ final class AttributeMethods {
 
 
 	/**
-	 * 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 @@ final class AttributeMethods {
 	}
 
 	/**
-	 * 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 @@ final class AttributeMethods {
 	}
 
 	/**
-	 * 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 @@ final class AttributeMethods {
 	}
 
 	/**
-	 * 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 @@ final class AttributeMethods {
 	}
 
 	/**
-	 * 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 @@ final class AttributeMethods {
 	}
 
 	/**
-	 * 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 @@ final class AttributeMethods {
 	}
 
 	/**
-	 * 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,7 +218,7 @@ final class AttributeMethods {
 	}
 
 	/**
-	 * Return the number of attributes in this collection.
+	 * Get the number of attributes in this collection.
 	 * @return the number of attributes
 	 */
 	int size() {
@@ -227,16 +226,17 @@ final class AttributeMethods {
 	}
 
 	/**
-	 * 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;
@@ -244,9 +244,9 @@ final class AttributeMethods {
 
 
 	/**
-	 * 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 @@ final class AttributeMethods {
 	}
 
 	/**
-	 * 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 @@ final class AttributeMethods {
 	}
 
 	/**
-	 * 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

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

@@ -47,11 +47,12 @@ import org.springframework.lang.Nullable;
  * {@code String} and {@code String[]} respectively to prevent potential early
  * class initialization.
  *
- * <p>If necessary, a {@link MergedAnnotation} can be {@link #synthesize()
+ * <p>If necessary, a {@code MergedAnnotation} can be {@linkplain #synthesize()
  * synthesized} back into an actual {@link java.lang.annotation.Annotation}.
  *
  * @author Phillip Webb
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 5.2
  * @param <A> the annotation type
  * @see MergedAnnotations
@@ -66,52 +67,52 @@ public interface MergedAnnotation<A extends Annotation> {
 
 
 	/**
-	 * Return the {@code Class} reference for the actual annotation type.
+	 * Get the {@code Class} reference for the actual annotation type.
 	 * @return the annotation type
 	 */
 	Class<A> getType();
 
 	/**
-	 * Return if the annotation is present on the source. Considers
-	 * {@link #isDirectlyPresent() direct annotations}, and
-	 * {@link #isMetaPresent() meta-annotation} annotations within the context
+	 * Determine if the annotation is present on the source. Considers
+	 * {@linkplain #isDirectlyPresent() directly present} and
+	 * {@linkplain #isMetaPresent() meta-present} annotations within the context
 	 * of the {@link SearchStrategy} used.
 	 * @return {@code true} if the annotation is present
 	 */
 	boolean isPresent();
 
 	/**
-	 * Return if the annotation is directly present on the source. A directly
-	 * present annotation is one that the user has explicitly defined and not
-	 * one that is {@link #isMetaPresent() meta-present} or
+	 * Determine if the annotation is directly present on the source. A directly
+	 * present annotation is one that the user has explicitly declared and not
+	 * one that is {@linkplain #isMetaPresent() meta-present} or
 	 * {@link Inherited @Inherited}.
 	 * @return {@code true} if the annotation is directly present
 	 */
 	boolean isDirectlyPresent();
 
 	/**
-	 * Return if the annotation is meta-present on the source. A meta-present
-	 * annotation is an annotation that the user hasn't explicitly defined, but
+	 * Determine if the annotation is meta-present on the source. A meta-present
+	 * annotation is an annotation that the user hasn't explicitly declared, but
 	 * has been used as a meta-annotation somewhere in the annotation hierarchy.
 	 * @return {@code true} if the annotation is meta-present
 	 */
 	boolean isMetaPresent();
 
 	/**
-	 * Return the depth of this annotation related to its use as a
+	 * Get the depth of this annotation related to its use as a
 	 * meta-annotation. A directly declared annotation has a depth of {@code 0},
 	 * a meta-annotation has a depth of {@code 1}, a meta-annotation on a
-	 * meta-annotation has a depth of {@code 2}, etc. A {@link #missing()
+	 * meta-annotation has a depth of {@code 2}, etc. A {@linkplain #missing()
 	 * missing} annotation will always return a depth of {@code -1}.
 	 * @return the annotation depth or {@code -1} if the annotation is missing
 	 */
 	int getDepth();
 
 	/**
-	 * Return the index of the aggregate collection containing this annotation.
+	 * Get the index of the aggregate collection containing this annotation.
 	 * Can be used to reorder a stream of annotations, for example, to give a
 	 * higher priority to annotations declared on a superclass or interface. A
-	 * {@link #missing() missing} annotation will always return an aggregate
+	 * {@linkplain #missing() missing} annotation will always return an aggregate
 	 * index of {@code -1}.
 	 * @return the aggregate index (starting at {@code 0}) or {@code -1} if the
 	 * annotation is missing
@@ -119,7 +120,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	int getAggregateIndex();
 
 	/**
-	 * Return the source that ultimately declared the annotation, or
+	 * Get the source that ultimately declared the annotation, or
 	 * {@code null} if the source is not known. If this merged annotation was
 	 * created {@link MergedAnnotations#from(java.lang.reflect.AnnotatedElement)
 	 * from} an {@link AnnotatedElement} then this source will be an element of
@@ -132,15 +133,15 @@ public interface MergedAnnotation<A extends Annotation> {
 	Object getSource();
 
 	/**
-	 * Return the parent of the meta-annotation, or {@code null} if the
-	 * annotation is not {@link #isMetaPresent() meta-present}.
+	 * Get the parent of the meta-annotation, or {@code null} if the
+	 * annotation is not {@linkplain #isMetaPresent() meta-present}.
 	 * @return the parent annotation or {@code null}
 	 */
 	@Nullable
 	MergedAnnotation<?> getParent();
 
 	/**
-	 * Return if the specified attribute name as a non-default value when
+	 * Determine if the specified attribute name has a non-default value when
 	 * compared to the annotation declaration.
 	 * @param attributeName the attribute name
 	 * @return {@code true} if the attribute value is different from the default
@@ -149,7 +150,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	boolean hasNonDefaultValue(String attributeName);
 
 	/**
-	 * Return if the specified attribute name as a default value when compared
+	 * Determine if the specified attribute name has a default value when compared
 	 * to the annotation declaration.
 	 * @param attributeName the attribute name
 	 * @return {@code true} if the attribute value is the same as the default
@@ -158,7 +159,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	boolean hasDefaultValue(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required byte attribute value from the annotation.
+	 * Get a required byte attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a byte
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -166,7 +167,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	byte getByte(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required byte array attribute value from the annotation.
+	 * Get a required byte array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a byte array
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -174,7 +175,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	byte[] getByteArray(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required boolean attribute value from the annotation.
+	 * Get a required boolean attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a boolean
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -182,7 +183,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	boolean getBoolean(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required boolean array attribute value from the annotation.
+	 * Get a required boolean array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a boolean array
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -190,7 +191,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	boolean[] getBooleanArray(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required char attribute value from the annotation.
+	 * Get a required char attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a char
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -198,7 +199,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	char getChar(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required char array attribute value from the annotation.
+	 * Get a required char array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a char array
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -206,7 +207,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	char[] getCharArray(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required short attribute value from the annotation.
+	 * Get a required short attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a short
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -214,7 +215,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	short getShort(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required short array attribute value from the annotation.
+	 * Get a required short array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a short array
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -222,7 +223,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	short[] getShortArray(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required int attribute value from the annotation.
+	 * Get a required int attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as an int
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -230,7 +231,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	int getInt(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required int array attribute value from the annotation.
+	 * Get a required int array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as an int array
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -238,7 +239,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	int[] getIntArray(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required long attribute value from the annotation.
+	 * Get a required long attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a long
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -246,7 +247,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	long getLong(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required long array attribute value from the annotation.
+	 * Get a required long array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a long array
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -254,7 +255,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	long[] getLongArray(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required double attribute value from the annotation.
+	 * Get a required double attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a double
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -262,7 +263,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	double getDouble(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required double array attribute value from the annotation.
+	 * Get a required double array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a double array
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -270,7 +271,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	double[] getDoubleArray(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required float attribute value from the annotation.
+	 * Get a required float attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a float
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -278,7 +279,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	float getFloat(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required float array attribute value from the annotation.
+	 * Get a required float array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a float array
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -286,7 +287,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	float[] getFloatArray(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required string attribute value from the annotation.
+	 * Get a required string attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a string
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -294,7 +295,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	String getString(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required string array attribute value from the annotation.
+	 * Get a required string array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a string array
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -302,7 +303,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	String[] getStringArray(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required class attribute value from the annotation.
+	 * Get a required class attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a class
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -310,7 +311,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	Class<?> getClass(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required class array attribute value from the annotation.
+	 * Get a required class array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return the value as a class array
 	 * @throws NoSuchElementException if there is no matching attribute
@@ -318,7 +319,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	Class<?>[] getClassArray(String attributeName) throws NoSuchElementException;
 
 	/**
-	 * Return a required enum attribute value from the annotation.
+	 * Get a required enum attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @param type the enum type
 	 * @return the value as a enum
@@ -327,7 +328,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	<E extends Enum<E>> E getEnum(String attributeName, Class<E> type) throws NoSuchElementException;
 
 	/**
-	 * Return a required enum array attribute value from the annotation.
+	 * Get a required enum array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @param type the enum type
 	 * @return the value as a enum array
@@ -336,7 +337,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	<E extends Enum<E>> E[] getEnumArray(String attributeName, Class<E> type) throws NoSuchElementException;
 
 	/**
-	 * Return a required annotation attribute value from the annotation.
+	 * Get a required annotation attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @param type the annotation type
 	 * @return the value as a {@link MergedAnnotation}
@@ -346,7 +347,7 @@ public interface MergedAnnotation<A extends Annotation> {
 			throws NoSuchElementException;
 
 	/**
-	 * Return a required annotation array attribute value from the annotation.
+	 * Get a required annotation array attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @param type the annotation type
 	 * @return the value as a {@link MergedAnnotation} array
@@ -356,7 +357,7 @@ public interface MergedAnnotation<A extends Annotation> {
 			throws NoSuchElementException;
 
 	/**
-	 * Return an optional attribute value from the annotation.
+	 * Get an optional attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @return an optional value or {@link Optional#empty()} if there is no
 	 * matching attribute
@@ -364,7 +365,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	Optional<Object> getValue(String attributeName);
 
 	/**
-	 * Return an optional attribute value from the annotation.
+	 * Get an optional attribute value from the annotation.
 	 * @param attributeName the attribute name
 	 * @param type the attribute type. Must be compatible with the underlying
 	 * attribute type or {@code Object.class}.
@@ -374,7 +375,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	<T> Optional<T> getValue(String attributeName, Class<T> type);
 
 	/**
-	 * Return the default attribute value from the annotation as specified in
+	 * Get the default attribute value from the annotation as specified in
 	 * the annotation declaration.
 	 * @param attributeName the attribute name
 	 * @return an optional of the default value or {@link Optional#empty()} if
@@ -383,7 +384,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	Optional<Object> getDefaultValue(String attributeName);
 
 	/**
-	 * Return the default attribute value from the annotation as specified in
+	 * Get the default attribute value from the annotation as specified in
 	 * the annotation declaration.
 	 * @param attributeName the attribute name
 	 * @param type the attribute type. Must be compatible with the underlying
@@ -394,7 +395,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	<T> Optional<T> getDefaultValue(String attributeName, Class<T> type);
 
 	/**
-	 * Return a new view of the annotation with all attributes that have default
+	 * Create a new view of the annotation with all attributes that have default
 	 * values removed.
 	 * @return a filtered view of the annotation without any attributes that
 	 * have a default value
@@ -403,7 +404,7 @@ public interface MergedAnnotation<A extends Annotation> {
 	MergedAnnotation<A> filterDefaultValues();
 
 	/**
-	 * Return a new view of the annotation with only attributes that match the
+	 * Create a new view of the annotation with only attributes that match the
 	 * given predicate.
 	 * @param predicate a predicate used to filter attribute names
 	 * @return a filtered view of the annotation
@@ -413,24 +414,24 @@ public interface MergedAnnotation<A extends Annotation> {
 	MergedAnnotation<A> filterAttributes(Predicate<String> predicate);
 
 	/**
-	 * Return a new view of the annotation that exposes non-merged attribute values.
-	 * Methods from this view will return attribute values with only alias mirroring
+	 * Create a new view of the annotation that exposes non-merged attribute values.
+	 * <p>Methods from this view will return attribute values with only alias mirroring
 	 * rules applied. Aliases to parent attributes will not be applied.
 	 * @return a non-merged view of the annotation
 	 */
 	MergedAnnotation<A> withNonMergedAttributes();
 
 	/**
-	 * Return an immutable {@link Map} that contains all the annotation attributes.
-	 * The {@link MapValues} options may be used to change the way that values are added.
+	 * Create an immutable {@link Map} that contains all the annotation attributes.
+	 * <p>The {@link MapValues options} may be used to change the way that values are added.
 	 * @param options map value options
 	 * @return an immutable map containing the attributes and values
 	 */
 	Map<String, Object> asMap(MapValues... options);
 
 	/**
-	 * Return a {@link Map} of the given type that contains all the annotation attributes.
-	 * The {@link MapValues} options may be used to change the way that values are added.
+	 * Create a {@link Map} of the given type that contains all the annotation attributes.
+	 * <p>The {@link MapValues options} may be used to change the way that values are added.
 	 * @param factory a map factory
 	 * @param options map value options
 	 * @return a map containing the attributes and values
@@ -438,18 +439,20 @@ public interface MergedAnnotation<A extends Annotation> {
 	<T extends Map<String, Object>> T asMap(Function<MergedAnnotation<?>, T> factory, MapValues... options);
 
 	/**
-	 * Return a type-safe synthesized version of this annotation that can be
-	 * used directly in code. The result is synthesized using a JDK {@link Proxy}
-	 * and as a result may incur a computational cost when first invoked.
+	 * Create a type-safe synthesized version of this annotation that can be
+	 * used directly in code.
+	 * <p>The result is synthesized using a JDK {@link Proxy} and as a result may
+	 * incur a computational cost when first invoked.
 	 * @return a synthesized version of the annotation.
 	 * @throws NoSuchElementException on a missing annotation
 	 */
 	A synthesize() throws NoSuchElementException;
 
 	/**
-	 * Optionally return type-safe synthesized version of this annotation based
-	 * on a condition predicate. The result is synthesized using a JDK {@link Proxy}
-	 * and as a result may incur a computational cost when first invoked.
+	 * Optionally create a type-safe synthesized version of this annotation based
+	 * on a condition predicate.
+	 * <p>The result is synthesized using a JDK {@link Proxy} and as a result may
+	 * incur a computational cost when first invoked.
 	 * @param condition the test to determine if the annotation can be synthesized
 	 * @return a optional containing the synthesized version of the annotation or
 	 * an empty optional if the condition doesn't match
@@ -460,7 +463,7 @@ public interface MergedAnnotation<A extends Annotation> {
 
 
 	/**
-	 * Return an {@link MergedAnnotation} that represents a missing annotation
+	 * Create a {@link MergedAnnotation} that represents a missing annotation
 	 * (i.e. one that is not present).
 	 * @return an instance representing a missing annotation
 	 */
@@ -479,11 +482,11 @@ public interface MergedAnnotation<A extends Annotation> {
 	}
 
 	/**
-	 * Create a new {@link MergedAnnotations} instance from the specified
+	 * Create a new {@link MergedAnnotation} instance from the specified
 	 * annotation.
 	 * @param source the source for the annotation. This source is used only for
 	 * information and logging. It does not need to <em>actually</em> contain
-	 * the specified annotations and it will not be searched.
+	 * the specified annotations, and it will not be searched.
 	 * @param annotation the annotation to include
 	 * @return a {@link MergedAnnotation} instance for the annotation
 	 */
@@ -492,9 +495,9 @@ public interface MergedAnnotation<A extends Annotation> {
 	}
 
 	/**
-	 * Create a new {@link MergedAnnotations} instance from the specified
+	 * Create a new {@link MergedAnnotation} instance from the specified
 	 * annotation type. The resulting annotation will not have any attribute
-	 * values, but may still be used to query default values.
+	 * values but may still be used to query default values.
 	 * @param annotationType the annotation type
 	 * @return a {@link MergedAnnotation} instance for the annotation
 	 */
@@ -503,8 +506,8 @@ public interface MergedAnnotation<A extends Annotation> {
 	}
 
 	/**
-	 * Create a new {@link MergedAnnotations} instance from the specified
-	 * annotation type and attributes maps.
+	 * Create a new {@link MergedAnnotation} instance from the specified
+	 * annotation type and attributes map.
 	 * @param annotationType the annotation type
 	 * @param attributes the annotation attributes or {@code null} if just default
 	 * values should be used
@@ -518,8 +521,8 @@ public interface MergedAnnotation<A extends Annotation> {
 	}
 
 	/**
-	 * Create a new {@link MergedAnnotations} instance from the specified
-	 * annotation type and attributes maps.
+	 * Create a new {@link MergedAnnotation} instance from the specified
+	 * annotation type and attributes map.
 	 * @param source the source for the annotation. This source is used only for
 	 * information and logging. It does not need to <em>actually</em> contain
 	 * the specified annotations and it will not be searched.
@@ -537,7 +540,7 @@ public interface MergedAnnotation<A extends Annotation> {
 
 	/**
 	 * Options that effect the way map values are
-	 * {@link MergedAnnotation#asMap(MapValues...) converted}.
+	 * {@linkplain MergedAnnotation#asMap(MapValues...) converted}.
 	 */
 	enum MapValues {
 

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

@@ -32,7 +32,7 @@ import org.springframework.util.MultiValueMap;
 
 /**
  * Collector implementations that provide various reduction operations for
- * {@link MergedAnnotation MergedAnnotations}.
+ * {@link MergedAnnotation} instances.
  *
  * @author Phillip Webb
  * @since 5.2
@@ -49,8 +49,8 @@ public abstract class MergedAnnotationCollectors {
 
 
 	/**
-	 * Returns a new {@link Collector} that accumulates merged annotations to a
-	 * {@link LinkedHashSet} containing {@link MergedAnnotation#synthesize()
+	 * Create a new {@link Collector} that accumulates merged annotations to a
+	 * {@link LinkedHashSet} containing {@linkplain MergedAnnotation#synthesize()
 	 * synthesized} versions.
 	 * @param <A> the annotation type
 	 * @return a {@link Collector} which collects and synthesizes the
@@ -62,8 +62,8 @@ public abstract class MergedAnnotationCollectors {
 	}
 
 	/**
-	 * Returns a new {@link Collector} that accumulates merged annotations to an
-	 * {@link Annotation} array containing {@link MergedAnnotation#synthesize()
+	 * Create a new {@link Collector} that accumulates merged annotations to an
+	 * {@link Annotation} array containing {@linkplain MergedAnnotation#synthesize()
 	 * synthesized} versions.
 	 * @param <A> the annotation type
 	 * @return a {@link Collector} which collects and synthesizes the
@@ -75,8 +75,8 @@ public abstract class MergedAnnotationCollectors {
 	}
 
 	/**
-	 * Returns a new {@link Collector} that accumulates merged annotations to an
-	 * {@link Annotation} array containing {@link MergedAnnotation#synthesize()
+	 * Create a new {@link Collector} that accumulates merged annotations to an
+	 * {@link Annotation} array containing {@linkplain MergedAnnotation#synthesize()
 	 * synthesized} versions.
 	 * @param <A> the annotation type
 	 * @param <R> the resulting array type
@@ -94,8 +94,8 @@ public abstract class MergedAnnotationCollectors {
 	}
 
 	/**
-	 * Returns a new {@link Collector} that accumulates merged annotations to an
-	 * {@link MultiValueMap} with items {@link MultiValueMap#add(Object, Object)
+	 * Create a new {@link Collector} that accumulates merged annotations to an
+	 * {@link MultiValueMap} with items {@linkplain MultiValueMap#add(Object, Object)
 	 * added} from each merged annotation
 	 * {@link MergedAnnotation#asMap(MapValues...) as a map}.
 	 * @param <A> the annotation type
@@ -111,8 +111,8 @@ public abstract class MergedAnnotationCollectors {
 	}
 
 	/**
-	 * Returns a new {@link Collector} that accumulates merged annotations to an
-	 * {@link MultiValueMap} with items {@link MultiValueMap#add(Object, Object)
+	 * Create a new {@link Collector} that accumulates merged annotations to an
+	 * {@link MultiValueMap} with items {@linkplain MultiValueMap#add(Object, Object)
 	 * added} from each merged annotation
 	 * {@link MergedAnnotation#asMap(MapValues...) as a map}.
 	 * @param <A> the annotation type

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

@@ -41,8 +41,8 @@ public abstract class MergedAnnotationPredicates {
 
 
 	/**
-	 * Returns a new {@link Predicate} that evaluates {@code true} if the
-	 * {@link MergedAnnotation#getType() merged annotation type} is contained in
+	 * Create a new {@link Predicate} that evaluates to {@code true} if the
+	 * {@linkplain MergedAnnotation#getType() merged annotation type} is contained in
 	 * the specified array.
 	 * @param <A> the annotation type
 	 * @param typeNames the names that should be matched
@@ -53,8 +53,8 @@ public abstract class MergedAnnotationPredicates {
 	}
 
 	/**
-	 * Returns a new {@link Predicate} that evaluates {@code true} if the
-	 * {@link MergedAnnotation#getType() merged annotation type} is contained in
+	 * Create a new {@link Predicate} that evaluates to {@code true} if the
+	 * {@linkplain MergedAnnotation#getType() merged annotation type} is contained in
 	 * the specified array.
 	 * @param <A> the annotation type
 	 * @param types the types that should be matched
@@ -65,8 +65,8 @@ public abstract class MergedAnnotationPredicates {
 	}
 
 	/**
-	 * Returns a new {@link Predicate} that evaluates {@code true} if the
-	 * {@link MergedAnnotation#getType() merged annotation type} is contained in
+	 * Create a new {@link Predicate} that evaluates to {@code true} if the
+	 * {@linkplain MergedAnnotation#getType() merged annotation type} is contained in
 	 * the collection.
 	 * @param <A> the annotation type
 	 * @param types the type names or classes that should be matched
@@ -79,12 +79,12 @@ public abstract class MergedAnnotationPredicates {
 	}
 
 	/**
-	 * Returns a new stateful, single use {@link Predicate} that matches only
+	 * Create a new stateful, single use {@link Predicate} that matches only
 	 * the first run of an extracted value. For example,
 	 * {@code MergedAnnotationPredicates.firstRunOf(MergedAnnotation::depth)}
 	 * will return the first annotation and a subsequent run of the same depth.
-	 * NOTE: this predicate only matches the first first run, once the extracted
-	 * value changes the predicate always returns {@code false}.
+	 * <p>NOTE: This predicate only matches the first first run. Once the extracted
+	 * value changes, the predicate always returns {@code false}.
 	 * @param valueExtractor function used to extract the value to check
 	 * @return a {@link Predicate} that matches the first run of the extracted
 	 * values
@@ -96,13 +96,13 @@ public abstract class MergedAnnotationPredicates {
 	}
 
 	/**
-	 * Returns a new stateful, single use {@link Predicate} that matches
-	 * annotations that are unique based on extracted key. For example
+	 * Create a new stateful, single use {@link Predicate} that matches
+	 * annotations that are unique based on the extracted key. For example
 	 * {@code MergedAnnotationPredicates.unique(MergedAnnotation::type)} will
-	 * match the first time a unique type is seen.
+	 * match the first time a unique type is encountered.
 	 * @param keyExtractor function used to extract the key used to test for
 	 * uniqueness
-	 * @return a {@link Predicate} that matches unique annotation based on the
+	 * @return a {@link Predicate} that matches a unique annotation based on the
 	 * extracted key
 	 */
 	public static <A extends Annotation, K> Predicate<MergedAnnotation<A>> unique(

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

@@ -31,7 +31,7 @@ import java.lang.annotation.Annotation;
 public interface MergedAnnotationSelector<A extends Annotation> {
 
 	/**
-	 * Return {@code true} if the existing annotation is known to be the best
+	 * Determine if the existing annotation is known to be the best
 	 * candidate and any subsequent selections may be skipped.
 	 * @param annotation the annotation to check
 	 * @return {@code true} if the annotation is known to be the best candidate

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

@@ -21,7 +21,7 @@ import java.util.function.Predicate;
 
 /**
  * {@link MergedAnnotationSelector} implementations that provide various options
- * for {@link MergedAnnotation MergedAnnotations}.
+ * for {@link MergedAnnotation} instances.
  *
  * @author Phillip Webb
  * @since 5.2

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

@@ -27,15 +27,15 @@ import org.springframework.lang.Nullable;
 
 /**
  * Provides access to a collection of merged annotations, usually obtained
- * from a source such as a {@link Class} or {@link Method}. Each merged
- * annotation represent a view where the attribute values may be "merged" from
- * different source values, typically:
+ * from a source such as a {@link Class} or {@link Method}.
+ *
+ * <p>Each merged annotation represents a view where the attribute values may be
+ * "merged" from different source values, typically:
  *
  * <ul>
  * <li>Explicit and Implicit {@link AliasFor @AliasFor} declarations on one or
- * attributes within the annotation.</li>
- * <li>Explicit {@link AliasFor @AliasFor} declarations for a
- * meta-annotation.</li>
+ * more attributes within the annotation.</li>
+ * <li>Explicit {@link AliasFor @AliasFor} declarations for a meta-annotation.</li>
  * <li>Convention based attribute aliases for a meta-annotation</li>
  * <li>From a meta-annotation declaration.</li>
  * </ul>
@@ -47,21 +47,21 @@ import org.springframework.lang.Nullable;
  * &#064;RequestMapping(method = RequestMethod.POST)
  * public &#064;interface PostMapping {
  *
- * 	&#064;AliasFor(attribute = "path")
- * 	String[] value() default {};
+ *     &#064;AliasFor(attribute = "path")
+ *     String[] value() default {};
  *
- * 	&#064;AliasFor(attribute = "value")
- * 	String[] path() default {};
+ *     &#064;AliasFor(attribute = "value")
+ *     String[] path() default {};
  *
  * }
  * </pre>
  *
- * If a method is annotated with {@code @PostMapping("/home")} it will contain
+ * <p>If a method is annotated with {@code @PostMapping("/home")} it will contain
  * merged annotations for both {@code @PostMapping} and the meta-annotation
  * {@code @RequestMapping}. The merged view of the {@code @RequestMapping}
  * annotation will contain the following attributes:
  *
- * <p><table>
+ * <p><table border="1">
  * <tr>
  * <th>Name</th>
  * <th>Value</th>
@@ -70,7 +70,7 @@ import org.springframework.lang.Nullable;
  * <tr>
  * <td>value</td>
  * <td>"/home"</td>
- * <td>Declared {@code @PostMapping}</td>
+ * <td>Declared in {@code @PostMapping}</td>
  * </tr>
  * <tr>
  * <td>path</td>
@@ -80,38 +80,39 @@ import org.springframework.lang.Nullable;
  * <tr>
  * <td>method</td>
  * <td>RequestMethod.POST</td>
- * <td>Declared meta-annotation</td>
+ * <td>Declared in meta-annotation</td>
  * </tr>
  * </table>
  *
- * <p>{@link MergedAnnotations} can be obtained {@link #from(AnnotatedElement)
- * from} any Java {@link AnnotatedElement}. They may also used for sources that
+ * <p>{@link MergedAnnotations} can be obtained {@linkplain #from(AnnotatedElement)
+ * from} any Java {@link AnnotatedElement}. They may also be used for sources that
  * don't use reflection (such as those that directly parse bytecode).
  *
- * <p>Different {@link SearchStrategy search strategies} can be used to locate
- * related source elements that contain the annotations to be aggregated
- * together. For example, {@link SearchStrategy#EXHAUSTIVE} will search both
- * superclasses and implemented interfaces.
+ * <p>Different {@linkplain SearchStrategy search strategies} can be used to locate
+ * related source elements that contain the annotations to be aggregated. For
+ * example, {@link SearchStrategy#EXHAUSTIVE} will search both superclasses and
+ * implemented interfaces.
  *
- * <p>From a {@link MergedAnnotations} instance you can either {@link #get(String)}
- * a single annotation, or {@link #stream() stream all annotations} or just
- * those that match {@link #stream(String) a specific type}. You can also
- * quickly tell if an annotation {@link #isPresent(String) is present}.
+ * <p>From a {@link MergedAnnotations} instance you can either
+ * {@linkplain #get(String) get} a single annotation, or {@linkplain #stream()
+ * stream all annotations} or just those that match {@linkplain #stream(String)
+ * a specific type}. You can also quickly tell if an annotation
+ * {@linkplain #isPresent(String) is present}.
  *
  * <p>Here are some typical examples:
  *
  * <pre class="code">
- * // is an annotation present or meta-present
+ * // is an annotation present or meta-present?
  * mergedAnnotations.isPresent(ExampleAnnotation.class);
  *
- * // get the merged "value" attribute of ExampleAnnotation (either direct or
+ * // get the merged "value" attribute of ExampleAnnotation (either directly or
  * // meta-present)
  * mergedAnnotations.get(ExampleAnnotation.class).getString("value");
  *
- * // get all meta-annotations but no direct annotations
+ * // get all meta-annotations but no directly present annotations
  * mergedAnnotations.stream().anyMatch(MergedAnnotation::isMetaPresent);
  *
- * // get all ExampleAnnotation declarations (include any meta-annotations) and
+ * // get all ExampleAnnotation declarations (including any meta-annotations) and
  * // print the merged "value" attributes
  * mergedAnnotations.stream(ExampleAnnotation.class).map(
  * 		a -> a.getString("value")).forEach(System.out::println);
@@ -128,41 +129,43 @@ import org.springframework.lang.Nullable;
 public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>> {
 
 	/**
-	 * Return if the specified annotation is either directly present, or
-	 * meta-present. Equivalent to calling
-	 * {@code get(annotationType).isPresent()}.
+	 * Determine if the specified annotation is either directly present or
+	 * meta-present.
+	 * <p>Equivalent to calling {@code get(annotationType).isPresent()}.
 	 * @param annotationType the annotation type to check
 	 * @return {@code true} if the annotation is present
 	 */
 	<A extends Annotation> boolean isPresent(Class<A> annotationType);
 
 	/**
-	 * Return if the specified annotation is directly present. Equivalent to
-	 * calling {@code get(annotationType).isDirectlyPresent()}.
-	 * @param annotationType the annotation type to check
+	 * Determine if the specified annotation is directly present.
+	 * <p>Equivalent to calling {@code get(annotationType).isDirectlyPresent()}.
+	 * @param annotationType the fully qualified class name of the annotation type
+	 * to check
 	 * @return {@code true} if the annotation is present
 	 */
 	boolean isPresent(String annotationType);
 
 	/**
-	 * Return if the specified annotation is directly present. Equivalent to
-	 * calling {@code get(annotationType).isDirectlyPresent()}.
+	 * Determine if the specified annotation is directly present.
+	 * <p>Equivalent to calling {@code get(annotationType).isDirectlyPresent()}.
 	 * @param annotationType the annotation type to check
 	 * @return {@code true} if the annotation is present
 	 */
 	<A extends Annotation> boolean isDirectlyPresent(Class<A> annotationType);
 
 	/**
-	 * Return if the specified annotation is either directly present, or
-	 * meta-present. Equivalent to calling
-	 * {@code get(annotationType).isPresent()}.
-	 * @param annotationType the annotation type to check
+	 * Determine if the specified annotation is either directly present or
+	 * meta-present.
+	 * <p>Equivalent to calling {@code get(annotationType).isPresent()}.
+	 * @param annotationType the fully qualified class name of the annotation type
+	 * to check
 	 * @return {@code true} if the annotation is present
 	 */
 	boolean isDirectlyPresent(String annotationType);
 
 	/**
-	 * Return the {@link MergedAnnotationSelectors#nearest() nearest} matching
+	 * Return the {@linkplain MergedAnnotationSelectors#nearest() nearest} matching
 	 * annotation or meta-annotation of the specified type, or
 	 * {@link MergedAnnotation#missing()} if none is present.
 	 * @param annotationType the annotation type to get
@@ -171,7 +174,7 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
 	<A extends Annotation> MergedAnnotation<A> get(Class<A> annotationType);
 
 	/**
-	 * Return the {@link MergedAnnotationSelectors#nearest() nearest} matching
+	 * Return the {@linkplain MergedAnnotationSelectors#nearest() nearest} matching
 	 * annotation or meta-annotation of the specified type, or
 	 * {@link MergedAnnotation#missing()} if none is present.
 	 * @param annotationType the annotation type to get
@@ -191,7 +194,7 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
 	 * type matching is required
 	 * @param selector a selector used to choose the most appropriate annotation
 	 * within an aggregate, or {@code null} to select the
-	 * {@link MergedAnnotationSelectors#nearest() nearest}.
+	 * {@linkplain MergedAnnotationSelectors#nearest() nearest}
 	 * @return a {@link MergedAnnotation} instance
 	 * @see MergedAnnotationPredicates
 	 * @see MergedAnnotationSelectors
@@ -201,19 +204,21 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
 			@Nullable MergedAnnotationSelector<A> selector);
 
 	/**
-	 * Return the {@link MergedAnnotationSelectors#nearest() nearest} matching
+	 * Return the {@linkplain MergedAnnotationSelectors#nearest() nearest} matching
 	 * annotation or meta-annotation of the specified type, or
 	 * {@link MergedAnnotation#missing()} if none is present.
-	 * @param annotationType the annotation type to get
+	 * @param annotationType the fully qualified class name of the annotation type
+	 * to get
 	 * @return a {@link MergedAnnotation} instance
 	 */
 	<A extends Annotation> MergedAnnotation<A> get(String annotationType);
 
 	/**
-	 * Return the {@link MergedAnnotationSelectors#nearest() nearest} matching
+	 * Return the {@linkplain MergedAnnotationSelectors#nearest() nearest} matching
 	 * annotation or meta-annotation of the specified type, or
 	 * {@link MergedAnnotation#missing()} if none is present.
-	 * @param annotationType the annotation type to get
+	 * @param annotationType the fully qualified class name of the annotation type
+	 * to get
 	 * @param predicate a predicate that must match, or {@code null} if only
 	 * type matching is required
 	 * @return a {@link MergedAnnotation} instance
@@ -225,12 +230,13 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
 	/**
 	 * Return a matching annotation or meta-annotation of the specified type, or
 	 * {@link MergedAnnotation#missing()} if none is present.
-	 * @param annotationType the annotation type to get
+	 * @param annotationType the fully qualified class name of the annotation type
+	 * to get
 	 * @param predicate a predicate that must match, or {@code null} if only
 	 * type matching is required
 	 * @param selector a selector used to choose the most appropriate annotation
 	 * within an aggregate, or {@code null} to select the
-	 * {@link MergedAnnotationSelectors#nearest() nearest}.
+	 * {@linkplain MergedAnnotationSelectors#nearest() nearest}
 	 * @return a {@link MergedAnnotation} instance
 	 * @see MergedAnnotationPredicates
 	 * @see MergedAnnotationSelectors
@@ -241,7 +247,7 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
 
 	/**
 	 * Stream all annotations and meta-annotations that match the specified
-	 * type. The resulting stream follows the same ordering rules are
+	 * type. The resulting stream follows the same ordering rules as
 	 * {@link #stream()}.
 	 * @param annotationType the annotation type to match
 	 * @return a stream of matching annotations
@@ -250,18 +256,19 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
 
 	/**
 	 * Stream all annotations and meta-annotations that match the specified
-	 * type.The resulting stream follows the same ordering rules are
+	 * type. The resulting stream follows the same ordering rules as
 	 * {@link #stream()}.
-	 * @param annotationType the annotation type to match
+	 * @param annotationType the fully qualified class name of the annotation type
+	 * to match
 	 * @return a stream of matching annotations
 	 */
 	<A extends Annotation> Stream<MergedAnnotation<A>> stream(String annotationType);
 
 	/**
-	 * Stream all contained annotations and meta-annotations contained in this
-	 * collection. The resulting stream is ordered first by the
-	 * {@link MergedAnnotation#getAggregateIndex() aggregate index}, and then by
-	 * the annotation depth (with the closest annotations first). This ordering
+	 * Stream all annotations and meta-annotations contained in this collection.
+	 * The resulting stream is ordered first by the
+	 * {@linkplain MergedAnnotation#getAggregateIndex() aggregate index} and then
+	 * by the annotation depth (with the closest annotations first). This ordering
 	 * means that, for most use-cases, the most suitable annotations appear
 	 * earliest in the stream.
 	 * @return a stream of annotations
@@ -272,12 +279,12 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
 	/**
 	 * Create a new {@link MergedAnnotations} instance containing all
 	 * annotations and meta-annotations from the specified element. The
-	 * resulting instance will not include any inherited annotations, if you
+	 * resulting instance will not include any inherited annotations. If you
 	 * want to include those as well you should use
 	 * {@link #from(AnnotatedElement, SearchStrategy)} with an appropriate
 	 * {@link SearchStrategy}.
 	 * @param element the source element
-	 * @return a {@link MergedAnnotations} instance containing the element
+	 * @return a {@link MergedAnnotations} instance containing the element's
 	 * annotations
 	 */
 	static MergedAnnotations from(AnnotatedElement element) {
@@ -332,7 +339,7 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
 	 * annotations.
 	 * @param source the source for the annotations. This source is used only
 	 * for information and logging. It does not need to <em>actually</em>
-	 * contain the specified annotations and it will not be searched.
+	 * contain the specified annotations, and it will not be searched.
 	 * @param annotations the annotations to include
 	 * @return a {@link MergedAnnotations} instance containing the annotations
 	 * @see #from(Annotation...)
@@ -347,7 +354,7 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
 	 * annotations.
 	 * @param source the source for the annotations. This source is used only
 	 * for information and logging. It does not need to <em>actually</em>
-	 * contain the specified annotations and it will not be searched.
+	 * contain the specified annotations, and it will not be searched.
 	 * @param annotations the annotations to include
 	 * @param repeatableContainers the repeatable containers that may be used by
 	 * meta-annotations
@@ -364,9 +371,10 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
 
 	/**
 	 * Search strategies supported by
-	 * {@link MergedAnnotations#from(AnnotatedElement, SearchStrategy)}. Each
-	 * strategy creates a different set of aggregates that will be combined to
-	 * create the final {@link MergedAnnotations}.
+	 * {@link MergedAnnotations#from(AnnotatedElement, SearchStrategy)}.
+	 *
+	 * <p>Each strategy creates a different set of aggregates that will be
+	 * combined to create the final {@link MergedAnnotations}.
 	 */
 	enum SearchStrategy {
 

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

@@ -27,7 +27,7 @@ import java.util.function.Predicate;
 import org.springframework.lang.Nullable;
 
 /**
- * A {@link AbstractMergedAnnotation} used as the implementation of
+ * An {@link AbstractMergedAnnotation} used as the implementation of
  * {@link MergedAnnotation#missing()}.
  *
  * @author Phillip Webb

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

@@ -37,11 +37,11 @@ final class PackagesAnnotationFilter implements AnnotationFilter {
 
 
 	PackagesAnnotationFilter(String... packages) {
-		Assert.notNull(packages, "Packages must not be null");
+		Assert.notNull(packages, "Packages array must not be null");
 		this.prefixes = new String[packages.length];
 		for (int i = 0; i < packages.length; i++) {
 			String pkg = packages[i];
-			Assert.hasText(pkg, "Package must not have empty elements");
+			Assert.hasText(pkg, "Packages array must not have empty elements");
 			this.prefixes[i] = pkg + ".";
 		}
 		Arrays.sort(this.prefixes);

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

@@ -33,7 +33,8 @@ import org.springframework.util.ReflectionUtils;
  * annotations. The {@link #standardRepeatables()} method provides a default
  * strategy that respects Java's {@link Repeatable @Repeatable} support and
  * should be suitable for most situations.
- * <p> The {@link #of} method can be used to register relationships for
+ *
+ * <p>The {@link #of} method can be used to register relationships for
  * annotations that do not wish to use {@link Repeatable @Repeatable}.
  *
  * <p>To completely disable repeatable support use {@link #none()}.
@@ -92,7 +93,7 @@ public abstract class RepeatableContainers {
 
 
 	/**
-	 * Return a {@link RepeatableContainers} instance that searches using Java's
+	 * Create a {@link RepeatableContainers} instance that searches using Java's
 	 * {@link Repeatable @Repeatable} annotation.
 	 * @return a {@link RepeatableContainers} instance
 	 */
@@ -101,7 +102,7 @@ public abstract class RepeatableContainers {
 	}
 
 	/**
-	 * Return a {@link RepeatableContainers} instance that uses a defined
+	 * Create a {@link RepeatableContainers} instance that uses a defined
 	 * container and repeatable type.
 	 * @param repeatable the contained repeatable annotation
 	 * @param container the container annotation or {@code null}. If specified,
@@ -118,7 +119,7 @@ public abstract class RepeatableContainers {
 	}
 
 	/**
-	 * Return a {@link RepeatableContainers} instance that does not expand any
+	 * Create a {@link RepeatableContainers} instance that does not expand any
 	 * repeatable annotations.
 	 * @return a {@link RepeatableContainers} instance
 	 */

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

@@ -41,7 +41,7 @@ import org.springframework.util.ReflectionUtils;
  * {@code BiFunction}. This allows various different annotation models to be
  * supported by the same class. For example, the attributes source might be an
  * actual {@link Annotation} instance where methods on the annotation instance
- * are {@link ReflectionUtils#invokeMethod(Method, Object) invoked} to extract
+ * are {@linkplain ReflectionUtils#invokeMethod(Method, Object) invoked} to extract
  * values. Equally, the source could be a simple {@link Map} with values
  * extracted using {@link Map#get(Object)}.
  *
@@ -49,12 +49,12 @@ import org.springframework.util.ReflectionUtils;
  * return type, namely:
  *
  * <p><table border="1">
- * <tr><th>Return Type</th><th >Extracted Type</th></tr>
+ * <tr><th>Return Type</th><th>Extracted Type</th></tr>
  * <tr><td>Class</td><td>Class or String</td></tr>
  * <tr><td>Class[]</td><td>Class[] or String[]</td></tr>
- * <tr><td>Annotation</td><td>Annotation, Map or Object compatible with the value
+ * <tr><td>Annotation</td><td>Annotation, Map, or Object compatible with the value
  * extractor</td></tr>
- * <tr><td>Annotation[]</td><td>Annotation[], Map[] or Object[] where elements are
+ * <tr><td>Annotation[]</td><td>Annotation[], Map[], or Object[] where elements are
  * compatible with the value extractor</td></tr>
  * <tr><td>Other types</td><td>An exact match or the appropriate primitive wrapper</td></tr>
  * </table>

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

@@ -273,7 +273,7 @@ final class TypeMappedAnnotations implements MergedAnnotations {
 
 	/**
 	 * {@link AnnotationsProcessor} used to detect if an annotation is directly
-	 * or meta-present.
+	 * present or meta-present.
 	 */
 	private static final class IsPresent implements AnnotationsProcessor<Object, Boolean> {
 
@@ -358,8 +358,7 @@ final class TypeMappedAnnotations implements MergedAnnotations {
 
 
 	/**
-	 * {@link AnnotationsProcessor} that finds a single
-	 * {@link MergedAnnotation}.
+	 * {@link AnnotationsProcessor} that finds a single {@link MergedAnnotation}.
 	 */
 	private class MergedAnnotationFinder<A extends Annotation>
 			implements AnnotationsProcessor<Object, MergedAnnotation<A>> {

spring-core/src/test/java/org/springframework/core/annotation/PackagesAnnotationFilterTests.java

@@ -32,21 +32,21 @@ public class PackagesAnnotationFilterTests {
 	public void createWhenPackagesIsNullThrowsException() {
 		assertThatIllegalArgumentException().isThrownBy(
 				() -> new PackagesAnnotationFilter((String[]) null)).withMessage(
-						"Packages must not be null");
+						"Packages array must not be null");
 	}
 
 	@Test
 	public void createWhenPackagesContainsNullThrowsException() {
 		assertThatIllegalArgumentException().isThrownBy(
 				() -> new PackagesAnnotationFilter((String) null)).withMessage(
-						"Package must not have empty elements");
+						"Packages array must not have empty elements");
 	}
 
 	@Test
 	public void createWhenPackagesContainsEmptyTextThrowsException() {
 		assertThatIllegalArgumentException().isThrownBy(
 				() -> new PackagesAnnotationFilter("")).withMessage(
-						"Package must not have empty elements");
+						"Packages array must not have empty elements");
 	}
 
 	@Test