Polish Javadoc for GroovyBeanDefinitionReader

spring-beans-groovy/src/main/java/org/springframework/beans/factory/groovy/GroovyBeanDefinitionReader.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.
@@ -31,6 +31,7 @@ import groovy.lang.GroovyObjectSupport;
 import groovy.lang.GroovyShell;
 import groovy.lang.GroovySystem;
 import groovy.lang.MetaClass;
+
 import org.codehaus.groovy.runtime.DefaultGroovyMethods;
 import org.codehaus.groovy.runtime.InvokerHelper;
 
@@ -58,8 +59,17 @@ import org.springframework.util.StringUtils;
 
 /**
  * A Groovy-based reader for Spring bean definitions: like a Groovy builder,
- * but more of a DSL for Spring configuration. Allows syntax like:
+ * but more of a DSL for Spring configuration.
+ *
+ * <p>This bean definition reader also understands XML bean definition files,
+ * allowing for seamless mixing and matching with Groovy bean definition files.
+ *
+ * <p>Typically applied to a
+ * {@link org.springframework.beans.factory.support.DefaultListableBeanFactory}
+ * or a {@link org.springframework.context.support.GenericApplicationContext},
+ * but can be used against any {@link BeanDefinitionRegistry} implementation.
  *
+ * <h3>Example Syntax</h3>
  * <pre class="code">
  * import org.hibernate.SessionFactory
  * import org.apache.commons.dbcp.BasicDataSource
@@ -84,8 +94,9 @@ import org.springframework.util.StringUtils;
  * }</pre>
  *
  * <p>You can also load resources containing beans defined in a Groovy script using
- * either the {@link #loadBeanDefinitions(org.springframework.core.io.Resource...)}
- * or {@link #loadBeanDefinitions(String...)} method, with a script looking as follows:
+ * either the {@link #loadBeanDefinitions(Resource...)} or
+ * {@link #loadBeanDefinitions(String...)} method, with a script looking similar to
+ * the following.
  *
  * <pre class="code">
  * import org.hibernate.SessionFactory
@@ -109,17 +120,10 @@ import org.springframework.util.StringUtils;
  *     }
  * }</pre>
  *
- * <p><b>This bean definition reader also understands XML bean definition files,
- * allowing for seamless mixing and matching with Groovy bean definition files.</b>
- *
- * <p>Typically applied to a
- * {@link org.springframework.beans.factory.support.DefaultListableBeanFactory}
- * or a {@link org.springframework.context.support.GenericApplicationContext},
- * but can be used against any {@link BeanDefinitionRegistry} implementation.
- *
  * @author Jeff Brown
  * @author Graeme Rocher
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 4.0
  * @see BeanDefinitionRegistry
  * @see org.springframework.beans.factory.support.DefaultListableBeanFactory
@@ -130,21 +134,20 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 
 	private final XmlBeanDefinitionReader xmlBeanDefinitionReader;
 
+	private final Map<String, String> namespaces = new HashMap<String, String>();
+
+	private final Map<String, DeferredProperty> deferredProperties = new HashMap<String, DeferredProperty>();
+
 	private MetaClass metaClass = GroovySystem.getMetaClassRegistry().getMetaClass(getClass());
 
 	private Binding binding;
 
 	private GroovyBeanDefinitionWrapper currentBeanDefinition;
 
-	private final Map <String, String> namespaces = new HashMap<String, String>();
-
-	private final Map<String, DeferredProperty> deferredProperties = new HashMap<String, DeferredProperty>();
-
 
 	/**
-	 * Create new GroovyBeanDefinitionReader for the given bean factory.
-	 * @param registry the BeanFactory to load bean definitions into,
-	 * in the form of a BeanDefinitionRegistry
+	 * Create a new {@code GroovyBeanDefinitionReader} for the given {@link BeanDefinitionRegistry}.
+	 * @param registry the {@code BeanDefinitionRegistry} to load bean definitions into
 	 */
 	public GroovyBeanDefinitionReader(BeanDefinitionRegistry registry) {
 		super(registry);
@@ -153,9 +156,9 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * Create new GroovyBeanDefinitionReader based on the given XmlBeanDefinitionReader,
-	 * using the same registry and delegating XML loading to it.
-	 * @param xmlBeanDefinitionReader the XmlBeanDefinitionReader to derive the registry
+	 * Create a new {@code GroovyBeanDefinitionReader} based on the given {@link XmlBeanDefinitionReader},
+	 * using its {@code BeanDefinitionRegistry} and delegating XML loading to it.
+	 * @param xmlBeanDefinitionReader the {@code XmlBeanDefinitionReader} to derive the registry
 	 * from and to delegate XML loading to
 	 */
 	public GroovyBeanDefinitionReader(XmlBeanDefinitionReader xmlBeanDefinitionReader) {
@@ -174,7 +177,7 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 
 	/**
 	 * Set the binding, i.e. the Groovy variables available in the scope
-	 * of a GroovyBeanDefinitionReader closure.
+	 * of a {@code GroovyBeanDefinitionReader} closure.
 	 */
 	public void setBinding(Binding binding) {
 		this.binding = binding;
@@ -192,9 +195,9 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 
 	/**
 	 * Load bean definitions from the specified Groovy script or XML file.
-	 * <p>Note that ".xml" files will be parsed as XML content; all other kinds
+	 * <p>Note that {@code ".xml"} files will be parsed as XML content; all other kinds
 	 * of resources will be parsed as Groovy scripts.
-	 * @param resource the resource descriptor for the Groovy script
+	 * @param resource the resource descriptor for the Groovy script or XML file
 	 * @return the number of bean definitions found
 	 * @throws BeanDefinitionStoreException in case of loading or parsing errors
 	 */
@@ -204,10 +207,10 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 
 	/**
 	 * Load bean definitions from the specified Groovy script or XML file.
-	 * <p>Note that ".xml" files will be parsed as XML content; all other kinds
+	 * <p>Note that {@code ".xml"} files will be parsed as XML content; all other kinds
 	 * of resources will be parsed as Groovy scripts.
-	 * @param encodedResource the resource descriptor for the Groovy script,
-	 * allowing to specify an encoding to use for parsing the file
+	 * @param encodedResource the resource descriptor for the Groovy script or XML file,
+	 * allowing specification of an encoding to use for parsing the file
 	 * @return the number of bean definitions found
 	 * @throws BeanDefinitionStoreException in case of loading or parsing errors
 	 */
@@ -255,14 +258,14 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	/**
 	 * Defines a set of beans for the given block or closure.
 	 * @param closure the block or closure
-	 * @return this GroovyBeanDefinitionReader instance
+	 * @return this {@code GroovyBeanDefinitionReader} instance
 	 */
 	public GroovyBeanDefinitionReader beans(Closure closure) {
 		return invokeBeanDefiningClosure(closure);
 	}
 
 	/**
-	 * Defines an inner bean definition.
+	 * Define an inner bean definition.
 	 * @param type the bean type
 	 * @return the bean definition
 	 */
@@ -307,7 +310,7 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * Define a Spring namespace definition to use.
+	 * Define a Spring XML namespace definition to use.
 	 * @param definition the namespace definition
 	 */
 	public void xmlns(Map<String, String> definition) {
@@ -419,7 +422,7 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	/**
 	 * When a method argument is only a closure it is a set of bean definitions.
 	 * @param callable the closure argument
-	 * @return this GroovyBeanDefinitionReader instance
+	 * @return this {@code GroovyBeanDefinitionReader} instance
 	 */
 	protected GroovyBeanDefinitionReader invokeBeanDefiningClosure(Closure callable) {
 		callable.setDelegate(this);
@@ -534,8 +537,8 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * Checks whether there are any {@link RuntimeBeanReference}s inside the Map
-	 * and converts it to a ManagedMap if necessary.
+	 * Checks whether there are any {@link RuntimeBeanReference}s inside the {@link Map}
+	 * and converts it to a {@link ManagedMap} if necessary.
 	 * @param map the original Map
 	 * @return either the original map or a managed copy of it
 	 */
@@ -556,8 +559,8 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * Checks whether there are any {@link RuntimeBeanReference}s inside the List
-	 * and converts it to a ManagedList if necessary.
+	 * Checks whether there are any {@link RuntimeBeanReference}s inside the {@link List}
+	 * and converts it to a {@link ManagedList} if necessary.
 	 * @param list the original List
 	 * @return either the original list or a managed copy of it
 	 */
@@ -578,7 +581,7 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * This method overrides property setting in the scope of the GroovyBeanDefinitionReader
+	 * This method overrides property setting in the scope of the {@code GroovyBeanDefinitionReader}
 	 * to set properties on the current bean definition.
 	 */
 	public void setProperty(String name, Object value) {
@@ -619,12 +622,12 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 
 	/**
 	 * This method overrides property retrieval in the scope of the
-	 * GroovyBeanDefinitionReader to either:
+	 * {@code GroovyBeanDefinitionReader} to either:
 	 * <ul>
 	 * <li>Retrieve a variable from the bean builder's binding if it exists
 	 * <li>Retrieve a RuntimeBeanReference for a specific bean if it exists
 	 * <li>Otherwise just delegate to MetaClass.getProperty which will resolve
-	 * properties from the GroovyBeanDefinitionReader itself
+	 * properties from the {@code GroovyBeanDefinitionReader} itself
 	 * </ul>
 	 */
 	public Object getProperty(String name) {