Polish PropertySource and Environment Javadoc

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

@@ -98,7 +98,8 @@ import org.springframework.stereotype.Component;
  * <h3>Using the {@code Environment} API</h3>
  * Externalized values may be looked up by injecting the Spring
  * {@link org.springframework.core.env.Environment Environment} into a
- * {@code @Configuration} class:
+ * {@code @Configuration} class using the {@code @Autowired} or the {@code @Inject}
+ * annotation:
  * <pre class="code">
  * &#064;Configuration
  * public class AppConfig {

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

@@ -49,10 +49,10 @@ import java.lang.annotation.Target;
  *     }
  * }</pre>
  *
- * Notice that the {@code Environment} object is @{@link Autowired} into the
- * configuration class and then used when populating the {@code TestBean}
- * object. Given the configuration above, a call to {@code testBean.getName()} will
- * return "myTestBean".
+ * Notice that the {@code Environment} object is @{@link
+ * org.springframework.beans.factory.annotation.Autowired Autowired} into the
+ * configuration class and then used when populating the {@code TestBean} object. Given
+ * the configuration above, a call to {@code testBean.getName()} will return "myTestBean".
  *
  * <h3>A note on property overriding with @PropertySource</h3>
  * In cases where a given property key exists in more than one {@code .properties}
@@ -91,13 +91,16 @@ import java.lang.annotation.Target;
  * if the {@code @Configuration} classes above were registered via component-scanning,
  * the ordering is difficult to predict.  In such cases - and if overriding is important -
  * it is recommended that the user fall back to using the programmatic PropertySource API.
- * See {@link org.springframework.core.env.ConfigurableEnvironment ConfigurableEnvironment} and
- * {@link org.springframework.core.env.MutablePropertySources MutablePropertySources} Javadoc
- * for details.
-
+ * See {@link org.springframework.core.env.ConfigurableEnvironment ConfigurableEnvironment}
+ * and * {@link org.springframework.core.env.MutablePropertySources MutablePropertySources}
+ * Javadoc for details.
  *
  * @author Chris Beams
  * @since 3.1
+ * @see Configuration
+ * @see org.springframework.core.env.PropertySource
+ * @see org.springframework.core.env.ConfigurableEnvironment#getPropertySources()
+ * @see org.springframework.core.env.MutablePropertySources
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
@@ -105,7 +108,7 @@ import java.lang.annotation.Target;
 public @interface PropertySource {
 
 	/**
-	 * Indicate the name of this PropertySource. If omitted, a name
+	 * Indicate the name of this property source. If omitted, a name
 	 * will be generated based on the description of the underlying
 	 * resource.
 	 * @see org.springframework.core.env.PropertySource#getName()

org.springframework.core/src/main/java/org/springframework/core/env/PropertySource.java

@@ -24,19 +24,26 @@ import org.springframework.util.Assert;
  * Abstract base class representing a source of key/value property pairs. The underlying
  * {@linkplain #getSource() source object} may be of any type {@code T} that encapsulates
  * properties. Examples include {@link java.util.Properties} objects, {@link java.util.Map}
- * objects, {@code ServletContext} and {@code ServletConfig} objects (for access to init parameters).
- * Explore the {@code PropertySource} type hierarchy to see provided implementations.
+ * objects, {@code ServletContext} and {@code ServletConfig} objects (for access to init
+ * parameters). Explore the {@code PropertySource} type hierarchy to see provided
+ * implementations.
  *
- * <p>{@code PropertySource} objects are not typically used in isolation, but rather through a
- * {@link PropertySources} object, which aggregates property sources and in conjunction with
- * a {@link PropertyResolver} implementation that can perform precedence-based searches across
- * the set of {@code PropertySources}.
+ * <p>{@code PropertySource} objects are not typically used in isolation, but rather
+ * through a {@link PropertySources} object, which aggregates property sources and in
+ * conjunction with a {@link PropertyResolver} implementation that can perform
+ * precedence-based searches across the set of {@code PropertySources}.
  *
- * <p>{@code PropertySource} identity is determined not based on the content of encapsulated
- * properties, but rather based on the {@link #getName() name} of the {@code PropertySource}
- * alone. This is useful for manipulating {@code PropertySource} objects when in collection
- * contexts. See operations in {@link MutablePropertySources} as well as the
- * {@link #named(String)} and {@link #toString()} methods for details.
+ * <p>{@code PropertySource} identity is determined not based on the content of
+ * encapsulated properties, but rather based on the {@link #getName() name} of the
+ * {@code PropertySource} alone. This is useful for manipulating {@code PropertySource}
+ * objects when in collection contexts. See operations in {@link MutablePropertySources}
+ * as well as the {@link #named(String)} and {@link #toString()} methods for details.
+ *
+ * <p>Note that when working with @{@link
+ * org.springframework.context.annotation.Configuration Configuration} classes that
+ * the @{@link org.springframework.context.annotation.PropertySource PropertySource}
+ * annotation provides a convenient and declarative way of adding property sources to the
+ * enclosing {@code Environment}.
  *
  * @author Chris Beams
  * @since 3.1
@@ -44,6 +51,7 @@ import org.springframework.util.Assert;
  * @see PropertyResolver
  * @see PropertySourcesPropertyResolver
  * @see MutablePropertySources
+ * @see org.springframework.context.annotation.PropertySource
  */
 public abstract class PropertySource<T> {
 

org.springframework.core/src/main/java/org/springframework/core/env/StandardEnvironment.java

@@ -67,7 +67,7 @@ package org.springframework.core.env;
  * {@link org.springframework.context.support.AbstractApplicationContext#refresh()
  * refresh()} method is called. This ensures that all PropertySources are available during
  * the container bootstrap process, including use by
- * {@link org.springframework.context.support.PropertySourcesPlaceholderConfigurer
+ * {@linkplain org.springframework.context.support.PropertySourcesPlaceholderConfigurer
  * property placeholder configurers}.
  *
  * @author Chris Beams
@@ -93,6 +93,7 @@ public class StandardEnvironment extends AbstractEnvironment {
 	 * </ul>
 	 * <p>Properties present in {@value #SYSTEM_PROPERTIES_PROPERTY_SOURCE_NAME} will
 	 * take precedence over those in {@value #SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME}.
+	 * @see AbstractEnvironment#customizePropertySources(MutablePropertySources)
 	 * @see #getSystemProperties()
 	 * @see #getSystemEnvironment()
 	 */

org.springframework.web.portlet/src/main/java/org/springframework/web/portlet/context/StandardPortletEnvironment.java

@@ -68,6 +68,7 @@ public class StandardPortletEnvironment extends StandardEnvironment {
 	 * initialized} once the actual {@link PortletConfig}, {@link PortletContext}, and
 	 * {@link ServletContext} objects are available.
 	 * @see StandardEnvironment#customizePropertySources
+	 * @see org.springframework.core.env.AbstractEnvironment#customizePropertySources
 	 * @see PortletConfigPropertySource
 	 * @see PortletContextPropertySource
 	 * @see AbstractRefreshablePortletApplicationContext#initPropertySources

org.springframework.web/src/main/java/org/springframework/web/context/support/StandardServletEnvironment.java

@@ -77,6 +77,7 @@ public class StandardServletEnvironment extends StandardEnvironment {
 	 * servlet property sources, but higher than system properties and environment
 	 * variables.
 	 * @see StandardEnvironment#customizePropertySources
+	 * @see org.springframework.core.env.AbstractEnvironment#customizePropertySources
 	 * @see ServletConfigPropertySource
 	 * @see ServletContextPropertySource
 	 * @see org.springframework.jndi.JndiPropertySource