Added Javadoc where necessary; polishing.

Author: cbeams

org.springframework.context/src/main/java/org/springframework/context/annotation/Bean.java

@@ -29,32 +29,32 @@
  * names and semantics of the attributes to this annotation are intentionally similar
  * to those of the {@literal <bean/>} element in the Spring XML schema. Deviations are
  * as follows:
- * 
+ *
  * <p>The Bean annotation does not provide attributes for scope, primary or lazy. Rather,
  * it should be used in conjunction with {@link Scope &#064;Scope},
  * {@link Primary &#064;Primary}, and {@link Lazy &#064;Lazy} annotations to achieve the
  * same semantics.
- * 
+ *
  * <p>While a {@link #name()} attribute is available, the default strategy for determining
  * the name of a bean is to use the name of the Bean method. This is convenient and
  * intuitive, but if explicit naming is desired, the {@link #name()} attribute may be used.
  * Also note that {@link #name()} accepts an array of strings. This is in order to allow
  * for specifying multiple names (i.e., aliases) for a single bean.
- * 
+ *
  * <h3>Constraints</h3>
  * <ul>
  *     <li>Bean methods are valid only when declared within an {@link Configuration &#064;Configuration}-annotated class
- * 	   <li>Bean methods must be non-void, non-final, non-private
- * 	   <li>Bean methods may not accept any arguments
+ *     <li>Bean methods must be non-void, non-final, non-private
+ *     <li>Bean methods may not accept any arguments
  *     <li>Bean methods may throw any exception, which will be caught and handled
  *  by the Spring container on processing of the declaring {@link Configuration &#064;Configuration} class.
  * </ul>
- * 
+ *
  * <h3>Usage</h3>
  * <p>Bean methods may reference other Bean methods by calling them directly. This ensures
  * that references between beans are strongly typed and navigable. So called 'inter-bean
  * references' are guaranteed to respect scoping and AOP semantics.
- * 
+ *
  * @author Rod Johnson
  * @author Costin Leau
  * @author Chris Beams

org.springframework.context/src/main/java/org/springframework/context/annotation/Configuration.java

@@ -31,32 +31,32 @@
  * Indicates that a class declares one or more {@link Bean} methods and may be processed
  * by the Spring container to generate bean definitions and service requests for those beans
  * at runtime.
- * 
+ *
  * <p>Configuration is meta-annotated as a {@link Component}, therefore Configuration
  * classes are candidates for component-scanning and may also take advantage of
  * {@link Autowired} at the field and method but not at the constructor level.
  * Externalized values may be wired into Configuration classes using the {@link Value}
  * annotation.
- * 
+ *
  * <p>May be used in conjunction with the {@link Lazy} annotation to indicate that all Bean
  * methods declared within this class are by default lazily initialized.
- * 
+ *
  * <h3>Constraints</h3>
  * <ul>
  *    <li>Configuration classes must be non-final
  *    <li>Configuration classes must be non-local (may not be declared within a method)
  *    <li>Configuration classes must have a default/no-arg constructor and may not use
  *        {@link Autowired} constructor parameters
  * </ul>
- * 
+ *
  * @author Rod Johnson
  * @author Chris Beams
  * @since 3.0
  * @see Import
  * @see Lazy
  * @see Bean
- * @see ConfigurationClassPostProcessor;
- * @see AnnotationConfigApplicationContext ;
+ * @see ConfigurationClassPostProcessor
+ * @see AnnotationConfigApplicationContext
  */
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
@@ -68,15 +68,15 @@
 	 * Explicitly specify the name of the Spring bean definition associated
 	 * with this Configuration class.  If left unspecified (the common case),
 	 * a bean name will be automatically generated.
-	 * 
+	 *
 	 * <p>The custom name applies only if the Configuration class is picked up via
 	 * component scanning or supplied directly to a {@link AnnotationConfigApplicationContext}.
 	 * If the Configuration class is registered as a traditional XML bean definition,
 	 * the name/id of the bean element will take precedence.
-	 * 
+	 *
 	 * @return the specified bean name, if any
 	 * @see org.springframework.beans.factory.support.DefaultBeanNameGenerator
 	 */
 	String value() default "";
-	
+
 }

org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClass.java

@@ -48,14 +48,14 @@ final class ConfigurationClass {
 
 	private final Resource resource;
 
-	private String beanName;
-
 	private final Map<String, Class> importedResources = new LinkedHashMap<String, Class>();
 
 	private final Set<ConfigurationClassMethod> methods = new LinkedHashSet<ConfigurationClassMethod>();
 
 	private final Map<String, Integer> overloadedMethodMap = new LinkedHashMap<String, Integer>();
 
+	private String beanName;
+
 
 	public ConfigurationClass(MetadataReader metadataReader, String beanName) {
 		this.metadata = metadataReader.getAnnotationMetadata();
@@ -102,11 +102,11 @@ public ConfigurationClass addMethod(ConfigurationClassMethod method) {
 		}
 		return this;
 	}
-	
+
 	public Set<ConfigurationClassMethod> getMethods() {
 		return this.methods;
 	}
-	
+
 	public void addImportedResource(String importedResource, Class readerClass) {
 		this.importedResources.put(importedResource, readerClass);
 	}

org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassBeanDefinitionReader.java

@@ -233,7 +233,7 @@ private void loadBeanDefinitionsFromImportedResources(Map<String, Class> importe
 			reader.loadBeanDefinitions(resource);
 		}
 	}
-	
+
 	/**
 	 * {@link RootBeanDefinition} marker subclass used to signify that a bean definition
 	 * created from a configuration class as opposed to any other configuration source.

org.springframework.context/src/main/java/org/springframework/context/annotation/ConfigurationClassParser.java

@@ -37,11 +37,11 @@
 import org.springframework.util.StringUtils;
 
 /**
- * Parses a {@link Configuration} class definition, populating a model (collection) of
+ * Parses a {@link Configuration} class definition, populating a collection of
  * {@link ConfigurationClass} objects (parsing a single Configuration class may result in
  * any number of ConfigurationClass objects because one Configuration class may import
  * another using the {@link Import} annotation).
- * 
+ *
  * <p>This class helps separate the concern of parsing the structure of a Configuration
  * class from the concern of registering {@link BeanDefinition} objects based on the
  * content of that model.
@@ -61,7 +61,7 @@ class ConfigurationClassParser {
 	private final ProblemReporter problemReporter;
 
 	private final Stack<ConfigurationClass> importStack = new ImportStack();
-	
+
 	private final Set<ConfigurationClass> configurationClasses =
 		new LinkedHashSet<ConfigurationClass>();
 

org.springframework.context/src/main/java/org/springframework/context/annotation/Import.java

@@ -18,25 +18,32 @@
 
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
-import java.lang.annotation.Inherited;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotation that allows one {@link Configuration} class to import another Configuration,
- * and thereby all its {@link Bean} definitions.
- * 
+ * Indicates one or more {@link Configuration} classes to import.
+ *
  * <p>Provides functionality equivalent to the {@literal <import/>} element in Spring XML.
- * Only supported for actual {@link Configuration} classes.
+ * Only supported for actual {@literal @Configuration}-annotated classes.
+ *
+ * <p>{@literal @Bean} definitions declared in imported {@literal @Configuration} classes
+ * should be accessed by using {@link Autowired @Autowired} injection.  Either the bean
+ * itself can be autowired, or the configuration class instance declaring the bean can be
+ * autowired.  The latter approach allows for explicit, IDE-friendly navigation between
+ * {@literal @Configuration} class methods.
+ *
+ * <p>If XML or other non-{@literal @Configuration} bean definition resources need to be
+ * imported, use {@link ImportResource @ImportResource}
  *
  * @author Chris Beams
  * @since 3.0
  * @see Configuration
+ * @see ImportResource
  */
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
-@Inherited
 @Documented
 public @interface Import {
 

org.springframework.context/src/main/java/org/springframework/context/annotation/ImportResource.java

@@ -25,13 +25,43 @@
 import org.springframework.beans.factory.support.BeanDefinitionReader;
 import org.springframework.beans.factory.xml.XmlBeanDefinitionReader;
 
+
+/**
+ * Indicates one or more resources containing bean definitions to import.
+ *
+ * <p>Like {@link Import @Import}, this annotation provides functionality similar to the
+ * {@literal <import/>} element in Spring XML.  It is typically used when
+ * designing {@link Configuration @Configuration} classes to be bootstrapped by
+ * {@link AnnotationConfigApplicationContext}, but where some XML functionality such as
+ * namespaces is still necessary.
+ *
+ * <p>By default, arguments to the {@link #value()} attribute will be processed using
+ * an {@link XmlBeanDefinitionReader}, i.e. it is assumed that resources are Spring
+ * {@literal <beans/>} XML files.  Optionally, the {@link #reader()} attribute may be
+ * supplied, allowing the user to specify a different {@link BeanDefinitionReader}
+ * implementation, such as
+ * {@link org.springframework.beans.factory.support.PropertiesBeanDefinitionReader}.
+ *
+ * @author Chris Beams
+ * @since 3.0
+ * @see Configuration
+ * @see Import
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 @Documented
 public @interface ImportResource {
 
+	/**
+	 * Resource paths to import.  Resource-loading prefixes such as {@literal classpath:} and
+	 * {@literal file:}, etc may be used.
+	 */
 	String[] value();
 
+	/**
+	 * {@link BeanDefinitionReader} implementation to use when processing resources specified
+	 * by the {@link #value()} attribute.
+	 */
 	Class<? extends BeanDefinitionReader> reader() default XmlBeanDefinitionReader.class;
 
 }