Improve documentation for annotation filters with component scanning

Prior to this commit the documentation for annotation-based include and
exclude filters used with component scanning did not explicitly mention
the fact that annotations are considered a match if they are either
present or meta-present on candidate classes.

This commit improves the documentation in this regard.

See gh-22551

Author: sbrannen

spring-context/src/main/resources/org/springframework/context/config/spring-context.xsd

@@ -515,7 +515,7 @@
 				<xsd:documentation><![CDATA[
     Controls the type of filtering to apply to the expression.
 
-    "annotation" indicates an annotation to be present at the type level in target components;
+    "annotation" indicates an annotation to be present or meta-present at the type level in target components;
     "assignable" indicates a class (or interface) that the target components are assignable to (extend/implement);
     "aspectj" indicates an AspectJ type pattern expression to be matched by the target components;
     "regex" indicates a regex pattern to be matched by the target components' class names;

spring-core/src/main/java/org/springframework/core/type/filter/AnnotationTypeFilter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -26,14 +26,20 @@
 import org.springframework.util.ClassUtils;
 
 /**
- * A simple filter which matches classes with a given annotation,
+ * A simple {@link TypeFilter} which matches classes with a given annotation,
  * checking inherited annotations as well.
  *
- * <p>The matching logic mirrors that of {@link java.lang.Class#isAnnotationPresent(Class)}.
+ * <p>By default, the matching logic mirrors that of
+ * {@link AnnotationUtils#getAnnotation(java.lang.reflect.AnnotatedElement, Class)},
+ * supporting annotations that are <em>present</em> or <em>meta-present</em> for a
+ * single level of meta-annotations. The search for meta-annotations my be disabled.
+ * Similarly, the search for annotations on interfaces may optionally be enabled.
+ * Consult the various constructors in this class for details.
  *
  * @author Mark Fisher
  * @author Ramnivas Laddad
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 2.5
  */
 public class AnnotationTypeFilter extends AbstractTypeHierarchyTraversingFilter {
@@ -44,20 +50,20 @@ public class AnnotationTypeFilter extends AbstractTypeHierarchyTraversingFilter
 
 
 	/**
-	 * Create a new AnnotationTypeFilter for the given annotation type.
-	 * This filter will also match meta-annotations. To disable the
+	 * Create a new {@code AnnotationTypeFilter} for the given annotation type.
+	 * <p>The filter will also match meta-annotations. To disable the
 	 * meta-annotation matching, use the constructor that accepts a
-	 * '{@code considerMetaAnnotations}' argument. The filter will
-	 * not match interfaces.
+	 * '{@code considerMetaAnnotations}' argument.
+	 * <p>The filter will not match interfaces.
 	 * @param annotationType the annotation type to match
 	 */
 	public AnnotationTypeFilter(Class<? extends Annotation> annotationType) {
 		this(annotationType, true, false);
 	}
 
 	/**
-	 * Create a new AnnotationTypeFilter for the given annotation type.
-	 * The filter will not match interfaces.
+	 * Create a new {@code AnnotationTypeFilter} for the given annotation type.
+	 * <p>The filter will not match interfaces.
 	 * @param annotationType the annotation type to match
 	 * @param considerMetaAnnotations whether to also match on meta-annotations
 	 */
@@ -66,7 +72,7 @@ public AnnotationTypeFilter(Class<? extends Annotation> annotationType, boolean
 	}
 
 	/**
-	 * Create a new {@link AnnotationTypeFilter} for the given annotation type.
+	 * Create a new {@code AnnotationTypeFilter} for the given annotation type.
 	 * @param annotationType the annotation type to match
 	 * @param considerMetaAnnotations whether to also match on meta-annotations
 	 * @param considerInterfaces whether to also match interfaces

src/docs/asciidoc/core/core-beans.adoc

@@ -5499,21 +5499,22 @@ component-scan element. That means that the two components are autodetected and
 wired together -- all without any bean configuration metadata provided in XML.
 
 NOTE: You can disable the registration of `AutowiredAnnotationBeanPostProcessor` and
-`CommonAnnotationBeanPostProcessor` by including the annotation-config attribute
+`CommonAnnotationBeanPostProcessor` by including the `annotation-config` attribute
 with a value of `false`.
 
 
 
 [[beans-scanning-filters]]
 === Using Filters to Customize Scanning
 
-By default, classes annotated with `@Component`, `@Repository`, `@Service`,
-`@Controller`, or a custom annotation that itself is annotated with `@Component` are the
-only detected candidate components. However, you can modify and extend this behavior
-by applying custom filters. Add them as `includeFilters` or `excludeFilters`
-parameters of the `@ComponentScan` annotation (or as `include-filter` or `exclude-filter`
-child elements of the `component-scan` element). Each filter element requires the `type`
-and `expression` attributes. The following table describes the filtering options:
+By default, classes annotated with `@Component`, `@Repository`, `@Service`, `@Controller`,
+`@Configuration`, or a custom annotation that itself is annotated with `@Component` are
+the only detected candidate components. However, you can modify and extend this behavior
+by applying custom filters. Add them as `includeFilters` or `excludeFilters` attributes of
+the `@ComponentScan` annotation (or as `<context:include-filter />` or
+`<context:exclude-filter />` child elements of the `<context:component-scan>` element in
+XML configuration). Each filter element requires the `type` and `expression` attributes.
+The following table describes the filtering options:
 
 [[beans-scanning-filters-tbl]]
 .Filter Types
@@ -5522,7 +5523,7 @@ and `expression` attributes. The following table describes the filtering options
 
 | annotation (default)
 | `org.example.SomeAnnotation`
-| An annotation to be present at the type level in target components.
+| An annotation to be _present_ or _meta-present_ at the type level in target components.
 
 | assignable
 | `org.example.SomeClass`
@@ -5534,11 +5535,11 @@ and `expression` attributes. The following table describes the filtering options
 
 | regex
 | `org\.example\.Default.*`
-| A regex expression to be matched by the target components class names.
+| A regex expression to be matched by the target components' class names.
 
 | custom
 | `org.example.MyTypeFilter`
-| A custom implementation of the `org.springframework.core.type .TypeFilter` interface.
+| A custom implementation of the `org.springframework.core.type.TypeFilter` interface.
 |===
 
 The following example shows the configuration ignoring all `@Repository` annotations
@@ -5571,10 +5572,11 @@ The following listing shows the equivalent XML:
 	</beans>
 ----
 
-NOTE: You can also disable the default filters by setting `useDefaultFilters=false` on the annotation or
- by providing `use-default-filters="false"` as an attribute of the `<component-scan/>` element. This,
-in effect, disables automatic detection of classes annotated with `@Component`, `@Repository`,
-`@Service`, `@Controller`, or `@Configuration`.
+NOTE: You can also disable the default filters by setting `useDefaultFilters=false` on the
+annotation or by providing `use-default-filters="false"` as an attribute of the
+`<component-scan/>` element. This effectively disables automatic detection of classes
+annotated or meta-annotated with `@Component`, `@Repository`, `@Service`, `@Controller`,
+`@RestController`, or `@Configuration`.