Added Javadoc where necessary; polishing.

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

@@ -55,8 +55,8 @@ import org.springframework.stereotype.Component;
  * @see Import
  * @see Lazy
  * @see Bean
- * @see ConfigurationClassPostProcessor;
- * @see AnnotationConfigApplicationContext ;
+ * @see ConfigurationClassPostProcessor
+ * @see AnnotationConfigApplicationContext
  */
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)

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();

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

@@ -37,7 +37,7 @@ import org.springframework.core.type.classreading.MetadataReaderFactory;
 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).

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

@@ -18,25 +18,32 @@ package org.springframework.context.annotation;
 
 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 java.lang.annotation.Target;
 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;
 
 }