Polish Javadoc for @ComponentScan

spring-context/src/main/java/org/springframework/context/annotation/ComponentScan.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -29,20 +29,20 @@ import org.springframework.core.type.filter.TypeFilter;
  * Configures component scanning directives for use with @{@link Configuration} classes.
  * Provides support parallel with Spring XML's {@code <context:component-scan>} element.
  *
- * <p>One of {@link #basePackageClasses()}, {@link #basePackages()} or its alias
- * {@link #value()} may be specified to define specific packages to scan.  If specific
- * packages are not defined scanning will occur from the package of the
- * class with this annotation.
+ * <p>Either {@link #basePackageClasses} or {@link #basePackages} (or its alias
+ * {@link #value}) may be specified to define specific packages to scan. If specific
+ * packages are not defined, scanning will occur from the package of the
+ * class that declares this annotation.
  *
  * <p>Note that the {@code <context:component-scan>} element has an
- * {@code annotation-config} attribute, however this annotation does not. This is because
+ * {@code annotation-config} attribute; however, this annotation does not. This is because
  * in almost all cases when using {@code @ComponentScan}, default annotation config
  * processing (e.g. processing {@code @Autowired} and friends) is assumed. Furthermore,
  * when using {@link AnnotationConfigApplicationContext}, annotation config processors are
  * always registered, meaning that any attempt to disable them at the
  * {@code @ComponentScan} level would be ignored.
  *
- * <p>See @{@link Configuration}'s javadoc for usage examples.
+ * <p>See {@link Configuration @Configuration}'s Javadoc for usage examples.
  *
  * @author Chris Beams
  * @author Juergen Hoeller
@@ -55,22 +55,24 @@ import org.springframework.core.type.filter.TypeFilter;
 public @interface ComponentScan {
 
 	/**
-	 * Alias for the {@link #basePackages()} attribute.
-	 * Allows for more concise annotation declarations e.g.:
-	 * {@code @ComponentScan("org.my.pkg")} instead of
-	 * {@code @ComponentScan(basePackages="org.my.pkg")}.
+	 * Alias for {@link #basePackages}.
+	 * <p>Allows for more concise annotation declarations if no other attributes
+	 * are needed &mdash; for example, {@code @ComponentScan("org.my.pkg")}
+	 * instead of {@code @ComponentScan(basePackages = "org.my.pkg")}.
 	 */
 	String[] value() default {};
 
 	/**
 	 * Base packages to scan for annotated components.
-	 * <p>{@link #value()} is an alias for (and mutually exclusive with) this attribute.
-	 * <p>Use {@link #basePackageClasses()} for a type-safe alternative to String-based package names.
+	 * <p>{@link #value} is an alias for (and mutually exclusive with) this
+	 * attribute.
+	 * <p>Use {@link #basePackageClasses} for a type-safe alternative to
+	 * String-based package names.
 	 */
 	String[] basePackages() default {};
 
 	/**
-	 * Type-safe alternative to {@link #basePackages()} for specifying the packages
+	 * Type-safe alternative to {@link #basePackages} for specifying the packages
 	 * to scan for annotated components. The package of each class specified will be scanned.
 	 * <p>Consider creating a special no-op marker class or interface in each package
 	 * that serves no purpose other than being referenced by this attribute.
@@ -99,14 +101,14 @@ public @interface ComponentScan {
 	 * necessary when using scopes in a proxy-style fashion.
 	 * <p>The default is defer to the default behavior of the component scanner used to
 	 * execute the actual scan.
-	 * <p>Note that setting this attribute overrides any value set for {@link #scopeResolver()}.
+	 * <p>Note that setting this attribute overrides any value set for {@link #scopeResolver}.
 	 * @see ClassPathBeanDefinitionScanner#setScopedProxyMode(ScopedProxyMode)
 	 */
 	ScopedProxyMode scopedProxy() default ScopedProxyMode.DEFAULT;
 
 	/**
 	 * Controls the class files eligible for component detection.
-	 * <p>Consider use of {@link #includeFilters()} and {@link #excludeFilters()}
+	 * <p>Consider use of {@link #includeFilters} and {@link #excludeFilters}
 	 * for a more flexible approach.
 	 */
 	String resourcePattern() default ClassPathScanningCandidateComponentProvider.DEFAULT_RESOURCE_PATTERN;
@@ -120,15 +122,15 @@ public @interface ComponentScan {
 	/**
 	 * Specifies which types are eligible for component scanning.
 	 * <p>Further narrows the set of candidate components from everything in
-	 * {@link #basePackages()} to everything in the base packages that matches
+	 * {@link #basePackages} to everything in the base packages that matches
 	 * the given filter or filters.
-	 * @see #resourcePattern()
+	 * @see #resourcePattern
 	 */
 	Filter[] includeFilters() default {};
 
 	/**
 	 * Specifies which types are not eligible for component scanning.
-	 * @see #resourcePattern()
+	 * @see #resourcePattern
 	 */
 	Filter[] excludeFilters() default {};
 
@@ -141,37 +143,39 @@ public @interface ComponentScan {
 
 
 	/**
-	 * Declares the type filter to be used as an {@linkplain ComponentScan#includeFilters()
-	 * include filter} or {@linkplain ComponentScan#excludeFilters() exclude filter}.
+	 * Declares the type filter to be used as an {@linkplain ComponentScan#includeFilters
+	 * include filter} or {@linkplain ComponentScan#excludeFilters exclude filter}.
 	 */
 	@Retention(RetentionPolicy.RUNTIME)
 	@Target({})
 	@interface Filter {
 
 		/**
-		 * The type of filter to use. Default is {@link FilterType#ANNOTATION}.
+		 * The type of filter to use.
+		 * <p>Default is {@link FilterType#ANNOTATION}.
 		 */
 		FilterType type() default FilterType.ANNOTATION;
 
 		/**
-		 * The class or classes to use as the filter. In the case of
-		 * {@link FilterType#ANNOTATION}, the class will be the annotation itself.
-		 * In the case of {@link FilterType#ASSIGNABLE_TYPE}, the class will be the
-		 * type that detected components should be assignable to. And in the case
-		 * of {@link FilterType#CUSTOM}, the class will be an implementation of
-		 * {@link TypeFilter}.
-		 * <p>When multiple classes are specified, OR logic is applied, e.g. "include
-		 * types annotated with {@code @Foo} OR {@code @Bar}".
+		 * The class or classes to use as the filter.
+		 * <p>In the case of {@link FilterType#ANNOTATION}, the class will be the
+		 * annotation itself. In the case of {@link FilterType#ASSIGNABLE_TYPE},
+		 * the class will be the type that detected components should be assignable
+		 * to. In the case of {@link FilterType#CUSTOM}, the class will be an
+		 * implementation of {@link TypeFilter}.
+		 * <p>When multiple classes are specified, <em>OR</em> logic is applied
+		 * &mdash; for example, "include types annotated with {@code @Foo} OR {@code @Bar}".
 		 * <p>Specifying zero classes is permitted but will have no effect on component
 		 * scanning.
 		 */
 		Class<?>[] value() default {};
 
 		/**
-		 * The String pattern (or patterns) to use for the filter, as an alternative to
-		 * specifying a Class {@link #value()}. In the case of {@link FilterType#ASPECTJ},
-		 * this is an AspectJ type pattern expression; in case of {@link FilterType#REGEX},
-		 * a regex pattern for the fully-qualified class names to match.
+		 * The String pattern (or patterns) to use for the filter, as an
+		 * alternative to specifying a Class {@link #value}.
+		 * <p>In the case of {@link FilterType#ASPECTJ}, this is an AspectJ
+		 * type pattern expression; in the case of {@link FilterType#REGEX},
+		 * this is a regex pattern for the fully-qualified class names to match.
 		 */
 		String[] pattern() default {};
 	}