Skip to content

Commit

Permalink
Polish Javadoc for MergedAnnotations
Browse files Browse the repository at this point in the history
  • Loading branch information
@sbrannen
sbrannen committed Mar 16, 2022
1 parent 8789b34 commit ad70878
Showing 1 changed file with 50 additions and 45 deletions.
95 changes: 50 additions & 45 deletions spring-core/src/main/java/org/springframework/core/annotation/MergedAnnotations.java
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright 2002-2020 the original author or authors.
* Copyright 2002-2022 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.
Expand Down Expand Up @@ -85,7 +85,7 @@
* </tr>
* </table>
*
* <p>{@link MergedAnnotations} can be obtained {@linkplain #from(AnnotatedElement)
* <p>{@code 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).
*
Expand All @@ -94,7 +94,7 @@
* example, {@link SearchStrategy#TYPE_HIERARCHY} will search both superclasses and
* implemented interfaces.
*
* <p>From a {@link MergedAnnotations} instance you can either
* <p>From a {@code 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
Expand Down Expand Up @@ -138,7 +138,7 @@
public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>> {

/**
* Determine if the specified annotation is either directly present or
* Determine if the specified annotation type is either directly present or
* meta-present.
* <p>Equivalent to calling {@code get(annotationType).isPresent()}.
* @param annotationType the annotation type to check
Expand All @@ -147,7 +147,7 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
<A extends Annotation> boolean isPresent(Class<A> annotationType);

/**
* Determine if the specified annotation is either directly present or
* Determine if the specified annotation type 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
Expand All @@ -157,15 +157,15 @@ public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>
boolean isPresent(String annotationType);

/**
* Determine if the specified annotation is directly present.
* Determine if the specified annotation type 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 directly present
*/
<A extends Annotation> boolean isDirectlyPresent(Class<A> annotationType);

/**
* Determine if the specified annotation is directly present.
* Determine if the specified annotation type is directly present.
* <p>Equivalent to calling {@code get(annotationType).isDirectlyPresent()}.
* @param annotationType the fully qualified class name of the annotation type
* to check
Expand Down Expand Up @@ -256,17 +256,17 @@ <A extends Annotation> MergedAnnotation<A> get(String annotationType,

/**
* Stream all annotations and meta-annotations that match the specified
* type. The resulting stream follows the same ordering rules as
* {@link #stream()}.
* type.
* <p>The resulting stream follows the same ordering rules as {@link #stream()}.
* @param annotationType the annotation type to match
* @return a stream of matching annotations
*/
<A extends Annotation> Stream<MergedAnnotation<A>> stream(Class<A> annotationType);

/**
* Stream all annotations and meta-annotations that match the specified
* type. The resulting stream follows the same ordering rules as
* {@link #stream()}.
* type.
* <p>The resulting stream follows the same ordering rules as {@link #stream()}.
* @param annotationType the fully qualified class name of the annotation type
* to match
* @return a stream of matching annotations
Expand All @@ -275,7 +275,7 @@ <A extends Annotation> MergedAnnotation<A> get(String annotationType,

/**
* Stream all annotations and meta-annotations contained in this collection.
* The resulting stream is ordered first by the
* <p>The resulting stream is ordered first by the
* {@linkplain MergedAnnotation#getAggregateIndex() aggregate index} and then
* by the annotation distance (with the closest annotations first). This ordering
* means that, for most use-cases, the most suitable annotations appear
Expand All @@ -287,13 +287,13 @@ <A extends Annotation> MergedAnnotation<A> get(String annotationType,

/**
* 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
* want to include those as well you should use
* annotations and meta-annotations from the specified element.
* <p>The 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's
* @return a {@code MergedAnnotations} instance containing the element's
* annotations
*/
static MergedAnnotations from(AnnotatedElement element) {
Expand All @@ -306,7 +306,7 @@ static MergedAnnotations from(AnnotatedElement element) {
* depending on the {@link SearchStrategy}, related inherited elements.
* @param element the source element
* @param searchStrategy the search strategy to use
* @return a {@link MergedAnnotations} instance containing the merged
* @return a {@code MergedAnnotations} instance containing the merged
* element annotations
*/
static MergedAnnotations from(AnnotatedElement element, SearchStrategy searchStrategy) {
Expand All @@ -321,7 +321,7 @@ static MergedAnnotations from(AnnotatedElement element, SearchStrategy searchStr
* @param searchStrategy the search strategy to use
* @param repeatableContainers the repeatable containers that may be used by
* the element annotations or the meta-annotations
* @return a {@link MergedAnnotations} instance containing the merged
* @return a {@code MergedAnnotations} instance containing the merged
* element annotations
*/
static MergedAnnotations from(AnnotatedElement element, SearchStrategy searchStrategy,
Expand All @@ -340,7 +340,7 @@ static MergedAnnotations from(AnnotatedElement element, SearchStrategy searchStr
* the element annotations or the meta-annotations
* @param annotationFilter an annotation filter used to restrict the
* annotations considered
* @return a {@link MergedAnnotations} instance containing the merged
* @return a {@code MergedAnnotations} instance containing the merged
* annotations for the supplied element
*/
static MergedAnnotations from(AnnotatedElement element, SearchStrategy searchStrategy,
Expand All @@ -355,7 +355,7 @@ static MergedAnnotations from(AnnotatedElement element, SearchStrategy searchStr
* Create a new {@link MergedAnnotations} instance from the specified
* annotations.
* @param annotations the annotations to include
* @return a {@link MergedAnnotations} instance containing the annotations
* @return a {@code MergedAnnotations} instance containing the annotations
* @see #from(Object, Annotation...)
*/
static MergedAnnotations from(Annotation... annotations) {
Expand All @@ -369,7 +369,7 @@ static MergedAnnotations from(Annotation... annotations) {
* for information and logging. It does not need to <em>actually</em>
* contain the specified annotations, and it will not be searched.
* @param annotations the annotations to include
* @return a {@link MergedAnnotations} instance containing the annotations
* @return a {@code MergedAnnotations} instance containing the annotations
* @see #from(Annotation...)
* @see #from(AnnotatedElement)
*/
Expand All @@ -386,7 +386,7 @@ static MergedAnnotations from(Object source, Annotation... annotations) {
* @param annotations the annotations to include
* @param repeatableContainers the repeatable containers that may be used by
* meta-annotations
* @return a {@link MergedAnnotations} instance containing the annotations
* @return a {@code MergedAnnotations} instance containing the annotations
*/
static MergedAnnotations from(Object source, Annotation[] annotations, RepeatableContainers repeatableContainers) {
return from(source, annotations, repeatableContainers, AnnotationFilter.PLAIN);
Expand All @@ -403,7 +403,7 @@ static MergedAnnotations from(Object source, Annotation[] annotations, Repeatabl
* meta-annotations
* @param annotationFilter an annotation filter used to restrict the
* annotations considered
* @return a {@link MergedAnnotations} instance containing the annotations
* @return a {@code MergedAnnotations} instance containing the annotations
*/
static MergedAnnotations from(Object source, Annotation[] annotations,
RepeatableContainers repeatableContainers, AnnotationFilter annotationFilter) {
Expand All @@ -416,16 +416,16 @@ static MergedAnnotations from(Object source, Annotation[] annotations,
/**
* Create a new {@link MergedAnnotations} instance from the specified
* collection of directly present annotations. This method allows a
* {@link MergedAnnotations} instance to be created from annotations that
* {@code MergedAnnotations} instance to be created from annotations that
* are not necessarily loaded using reflection. The provided annotations
* must all be {@link MergedAnnotation#isDirectlyPresent() directly present}
* and must have an {@link MergedAnnotation#getAggregateIndex() aggregate
* index} of {@code 0}.
* <p>The resulting {@link MergedAnnotations} instance will contain both the
* specified annotations, and any meta-annotations that can be read using
* <p>The resulting {@code MergedAnnotations} instance will contain both the
* specified annotations and any meta-annotations that can be read using
* reflection.
* @param annotations the annotations to include
* @return a {@link MergedAnnotations} instance containing the annotations
* @return a {@code MergedAnnotations} instance containing the annotations
* @see MergedAnnotation#of(ClassLoader, Object, Class, java.util.Map)
*/
static MergedAnnotations of(Collection<MergedAnnotation<?>> annotations) {
Expand All @@ -435,7 +435,8 @@ static MergedAnnotations of(Collection<MergedAnnotation<?>> annotations) {

/**
* Search strategies supported by
* {@link MergedAnnotations#from(AnnotatedElement, SearchStrategy)}.
* {@link MergedAnnotations#from(AnnotatedElement, SearchStrategy)} and
* variants of that method.
*
* <p>Each strategy creates a different set of aggregates that will be
* combined to create the final {@link MergedAnnotations}.
Expand All @@ -451,37 +452,41 @@ enum SearchStrategy {

/**
* Find all directly declared annotations as well as any
* {@link Inherited @Inherited} superclass annotations. This strategy
* is only really useful when used with {@link Class} types since the
* {@link Inherited @Inherited} annotation is ignored for all other
* {@linkplain AnnotatedElement annotated elements}. This strategy does
* not search implemented interfaces.
* {@link Inherited @Inherited} superclass annotations.
* <p>This strategy is only really useful when used with {@link Class}
* types since the {@link Inherited @Inherited} annotation is ignored for
* all other {@linkplain AnnotatedElement annotated elements}.
* <p>This strategy does not search implemented interfaces.
*/
INHERITED_ANNOTATIONS,

/**
* Find all directly declared and superclass annotations. This strategy
* is similar to {@link #INHERITED_ANNOTATIONS} except the annotations
* do not need to be meta-annotated with {@link Inherited @Inherited}.
* This strategy does not search implemented interfaces.
* Find all directly declared and superclass annotations.
* <p>This strategy is similar to {@link #INHERITED_ANNOTATIONS} except
* the annotations do not need to be meta-annotated with
* {@link Inherited @Inherited}.
* <p>This strategy does not search implemented interfaces.
*/
SUPERCLASS,

/**
* Perform a full search of the entire type hierarchy, including
* superclasses and implemented interfaces. Superclass annotations do
* not need to be meta-annotated with {@link Inherited @Inherited}.
* superclasses and implemented interfaces.
* <p>Superclass annotations do not need to be meta-annotated with
* {@link Inherited @Inherited}.
*/
TYPE_HIERARCHY,

/**
* Perform a full search of the entire type hierarchy on the source
* <em>and</em> any enclosing classes. This strategy is similar to
* {@link #TYPE_HIERARCHY} except that {@linkplain Class#getEnclosingClass()
* enclosing classes} are also searched. Superclass annotations do not
* need to be meta-annotated with {@link Inherited @Inherited}. When
* searching a {@link Method} source, this strategy is identical to
* {@link #TYPE_HIERARCHY}.
* <em>and</em> any enclosing classes.
* <p>This strategy is similar to {@link #TYPE_HIERARCHY} except that
* {@linkplain Class#getEnclosingClass() enclosing classes} are also
* searched.
* <p>Superclass annotations do not need to be meta-annotated with
* {@link Inherited @Inherited}.
* <p>When searching a {@link Method} source, this strategy is identical
* to {@link #TYPE_HIERARCHY}.
*/
TYPE_HIERARCHY_AND_ENCLOSING_CLASSES
}
Expand Down

0 comments on commit ad70878

Please sign in to comment.