Added Javadoc where necessary; polishing.

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

@@ -44,8 +44,8 @@ import org.springframework.beans.factory.annotation.Autowire;
  * <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 must be non-void, non-final, non-private
- * 	   <li>Bean methods may not accept any arguments
+ *     <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>

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 ConfigurationClassPostProcessor
- * @see AnnotationConfigApplicationContext ;
+ * @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,
+ * Indicates one or more {@link Configuration} classes to import.
- * and thereby all its {@link Bean} definitions.
  *
  * <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;
 
 }

org.springframework.samples.petclinic/src/main/java/org/springframework/samples/petclinic/config/DbcpDataSourceFactory.java

@@ -46,216 +46,216 @@ import org.springframework.core.io.Resource;
  */
 public class DbcpDataSourceFactory implements FactoryBean<DataSource>, DisposableBean {
 
-    // configurable properties
+	// configurable properties
 
-    private String driverClassName;
+	private String driverClassName;
 
-    private String url;
+	private String url;
 
-    private String username;
+	private String username;
 
-    private String password;
+	private String password;
 
-    private boolean populate;
+	private boolean populate;
 
-    private Resource schemaLocation;
+	private Resource schemaLocation;
 
-    private Resource dataLocation;
+	private Resource dataLocation;
 
-    private Resource dropLocation;
+	private Resource dropLocation;
 
-    /**
+	/**
-     * The object created by this factory.
+	 * The object created by this factory.
-     */
+	 */
-    private BasicDataSource dataSource;
+	private BasicDataSource dataSource;
 
-    public void setDriverClassName(String driverClassName) {
+	public void setDriverClassName(String driverClassName) {
-        this.driverClassName = driverClassName;
+		this.driverClassName = driverClassName;
-    }
+	}
 
-    /**
+	/**
-     * The data source connection URL
+	 * The data source connection URL
-     */
+	 */
-    public void setUrl(String url) {
+	public void setUrl(String url) {
-        this.url = url;
+		this.url = url;
-    }
+	}
 
-    /**
+	/**
-     * The data source username
+	 * The data source username
-     */
+	 */
-    public void setUsername(String username) {
+	public void setUsername(String username) {
-        this.username = username;
+		this.username = username;
-    }
+	}
 
-    /**
+	/**
-     *The data source password
+	 *The data source password
-     */
+	 */
-    public void setPassword(String password) {
+	public void setPassword(String password) {
-        this.password = password;
+		this.password = password;
-    }
+	}
 
-    /**
+	/**
-     * Indicates that the data base should be populated from the schema and data locations
+	 * Indicates that the data base should be populated from the schema and data locations
-     */
+	 */
-    public void setPopulate(boolean populate) {
+	public void setPopulate(boolean populate) {
-        this.populate = populate;
+		this.populate = populate;
-    }
+	}
 
-    /**
+	/**
-     * Sets the location of the file containing the schema DDL to export to the database.
+	 * Sets the location of the file containing the schema DDL to export to the database.
-     * @param schemaLocation the location of the database schema DDL
+	 * @param schemaLocation the location of the database schema DDL
-     */
+	 */
-    public void setSchemaLocation(Resource schemaLocation) {
+	public void setSchemaLocation(Resource schemaLocation) {
-        this.schemaLocation = schemaLocation;
+		this.schemaLocation = schemaLocation;
-    }
+	}
 
-    /**
+	/**
-     * Sets the location of the file containing the data to load into the database.
+	 * Sets the location of the file containing the data to load into the database.
-     * @param testDataLocation the location of the data file
+	 * @param testDataLocation the location of the data file
-     */
+	 */
-    public void setDataLocation(Resource testDataLocation) {
+	public void setDataLocation(Resource testDataLocation) {
-        this.dataLocation = testDataLocation;
+		this.dataLocation = testDataLocation;
-    }
+	}
 
-    /**
+	/**
-     * Sets the location of the file containing the drop scripts for the database.
+	 * Sets the location of the file containing the drop scripts for the database.
-     * @param testDataLocation the location of the data file
+	 * @param testDataLocation the location of the data file
-     */
+	 */
-    public void setDropLocation(Resource testDropLocation) {
+	public void setDropLocation(Resource testDropLocation) {
-        this.dropLocation = testDropLocation;
+		this.dropLocation = testDropLocation;
-    }
+	}
 
-    // implementing FactoryBean
+	// implementing FactoryBean
 
-    // this method is called by Spring to expose the DataSource as a bean
+	// this method is called by Spring to expose the DataSource as a bean
-    public DataSource getObject() throws Exception {
+	public DataSource getObject() throws Exception {
-        if (dataSource == null) {
+		if (dataSource == null) {
-            initDataSource();
+			initDataSource();
-        }
+		}
-        return dataSource;
+		return dataSource;
-    }
+	}
 
-    public Class<DataSource> getObjectType() {
+	public Class<DataSource> getObjectType() {
-        return DataSource.class;
+		return DataSource.class;
-    }
+	}
 
-    public boolean isSingleton() {
+	public boolean isSingleton() {
-        return true;
+		return true;
-    }
+	}
 
-    // implementing DisposableBean
+	// implementing DisposableBean
 
-    public void destroy() throws Exception {
+	public void destroy() throws Exception {
-    	dataSource.close();
+		dataSource.close();
-    }
+	}
 
-    // internal helper methods
+	// internal helper methods
 
-    // encapsulates the steps involved in initializing the data source: creating it, and populating it
+	// encapsulates the steps involved in initializing the data source: creating it, and populating it
-    private void initDataSource() {
+	private void initDataSource() {
-        // create the database source first
+		// create the database source first
-        this.dataSource = createDataSource();
+		this.dataSource = createDataSource();
 
-        if (this.populate) {
+		if (this.populate) {
-        	// now populate the database by loading the schema and data
+			// now populate the database by loading the schema and data
-        	populateDataSource();
+			populateDataSource();
-        }
+		}
-    }
+	}
 
-    private BasicDataSource createDataSource() {
+	private BasicDataSource createDataSource() {
-    	BasicDataSource dataSource = new BasicDataSource();
+		BasicDataSource dataSource = new BasicDataSource();
-        dataSource.setDriverClassName(this.driverClassName);
+		dataSource.setDriverClassName(this.driverClassName);
-        dataSource.setUrl(this.url);
+		dataSource.setUrl(this.url);
-        dataSource.setUsername(this.username);
+		dataSource.setUsername(this.username);
-        dataSource.setPassword(this.password);
+		dataSource.setPassword(this.password);
-        return dataSource;
+		return dataSource;
-    }
+	}
 
-    private void populateDataSource() {
+	private void populateDataSource() {
-        DatabasePopulator populator = new DatabasePopulator(dataSource);
+		DatabasePopulator populator = new DatabasePopulator(dataSource);
-        if (dropLocation != null) {
+		if (dropLocation != null) {
-            try {
+			try {
-        		populator.populate(this.dropLocation);
+				populator.populate(this.dropLocation);
-            } 
+			} 
-            catch (Exception e) {
+			catch (Exception e) {
-               	// ignore
+			   	// ignore
-            }
+			}
-        }
+		}
-        populator.populate(this.schemaLocation);
+		populator.populate(this.schemaLocation);
-        populator.populate(this.dataLocation);
+		populator.populate(this.dataLocation);
-    }
+	}
 
-    /**
+	/**
-     * Populates a in memory data source with data.
+	 * Populates a in memory data source with data.
-     */
+	 */
-    private class DatabasePopulator {
+	private class DatabasePopulator {
 
-        private DataSource dataSource;
+		private DataSource dataSource;
 
-        /**
+		/**
-         * Creates a new database populator.
+		 * Creates a new database populator.
-         * @param dataSource the data source that will be populated.
+		 * @param dataSource the data source that will be populated.
-         */
+		 */
-        public DatabasePopulator(DataSource dataSource) {
+		public DatabasePopulator(DataSource dataSource) {
-            this.dataSource = dataSource;
+			this.dataSource = dataSource;
-        }
+		}
 
-        /**
+		/**
-         * Populate the database executing the statements in the provided resource against the database
+		 * Populate the database executing the statements in the provided resource against the database
-         * @param sqlFile spring resource containing SQL to run against the db
+		 * @param sqlFile spring resource containing SQL to run against the db
-         */
+		 */
-        public void populate(Resource sqlFile) {
+		public void populate(Resource sqlFile) {
-            Connection connection = null;
+			Connection connection = null;
-            try {
+			try {
-                connection = dataSource.getConnection();
+				connection = dataSource.getConnection();
-                try {
+				try {
-                    String sql = parseSqlIn(sqlFile);
+					String sql = parseSqlIn(sqlFile);
-                    executeSql(sql, connection);
+					executeSql(sql, connection);
-                } catch (IOException e) {
+				} catch (IOException e) {
-                    throw new RuntimeException("I/O exception occurred accessing the database schema file", e);
+					throw new RuntimeException("I/O exception occurred accessing the database schema file", e);
-                } catch (SQLException e) {
+				} catch (SQLException e) {
-                    throw new RuntimeException("SQL exception occurred exporting database schema", e);
+					throw new RuntimeException("SQL exception occurred exporting database schema", e);
-                }
+				}
-            } catch (SQLException e) {
+			} catch (SQLException e) {
-                throw new RuntimeException("SQL exception occurred acquiring connection", e);
+				throw new RuntimeException("SQL exception occurred acquiring connection", e);
-            } finally {
+			} finally {
-                if (connection != null) {
+				if (connection != null) {
-                    try {
+					try {
-                        connection.close();
+						connection.close();
-                    } catch (SQLException e) {
+					} catch (SQLException e) {
-                    }
+					}
-                }
+				}
-            }
+			}
-        }
+		}
 
-        // utility method to read a .sql txt input stream
+		// utility method to read a .sql txt input stream
-        private String parseSqlIn(Resource resource) throws IOException {
+		private String parseSqlIn(Resource resource) throws IOException {
-            InputStream is = null;
+			InputStream is = null;
-            try {
+			try {
-                is = resource.getInputStream();
+				is = resource.getInputStream();
-                BufferedReader reader = new BufferedReader(new InputStreamReader(is));
+				BufferedReader reader = new BufferedReader(new InputStreamReader(is));
 
-                StringWriter sw = new StringWriter();
+				StringWriter sw = new StringWriter();
-                BufferedWriter writer = new BufferedWriter(sw);
+				BufferedWriter writer = new BufferedWriter(sw);
 
-                for (int c=reader.read(); c != -1; c=reader.read()) {
+				for (int c=reader.read(); c != -1; c=reader.read()) {
-                    writer.write(c);
+					writer.write(c);
-                }
+				}
-                writer.flush();
+				writer.flush();
-                return sw.toString();
+				return sw.toString();
 
-            } finally {
+			} finally {
-                if (is != null) {
+				if (is != null) {
-                    is.close();
+					is.close();
-                }
+				}
-            }
+			}
-        }
+		}
 
-        // utility method to run the parsed sql
+		// utility method to run the parsed sql
-        private void executeSql(String sql, Connection connection) throws SQLException {
+		private void executeSql(String sql, Connection connection) throws SQLException {
-            Statement statement = connection.createStatement();
+			Statement statement = connection.createStatement();
-            statement.execute(sql);
+			statement.execute(sql);
-        }
+		}
-    }
+	}
 
 }