From 710fdc73f1d41696ee14e24cbd0725b95590566c Mon Sep 17 00:00:00 2001
From: Sam Brannen <sam@sambrannen.com>
Date: Sat, 21 Dec 2013 14:00:47 +0100
Subject: [PATCH] Polish Javadoc for Groovy bean support classes

---
 .../groovy/GroovyBeanDefinitionReader.java    | 54 +++++++++++--------
 .../GenericGroovyApplicationContext.java      | 24 ++++++---
 2 files changed, 47 insertions(+), 31 deletions(-)

diff --git a/spring-beans-groovy/src/main/java/org/springframework/beans/factory/groovy/GroovyBeanDefinitionReader.java b/spring-beans-groovy/src/main/java/org/springframework/beans/factory/groovy/GroovyBeanDefinitionReader.java
index 6e421c6f4b..534f80cd94 100644
--- a/spring-beans-groovy/src/main/java/org/springframework/beans/factory/groovy/GroovyBeanDefinitionReader.java
+++ b/spring-beans-groovy/src/main/java/org/springframework/beans/factory/groovy/GroovyBeanDefinitionReader.java
@@ -56,10 +56,11 @@ import org.springframework.core.io.support.EncodedResource;
 import org.springframework.core.io.support.ResourcePatternUtils;
 
 /**
- * A Groovy-based reader for Spring bean definitions: Like a Groovy builder,
+ * A Groovy-based reader for Spring bean definitions: like a Groovy builder,
  * but more of a DSL for Spring configuration. Allows syntax like:
  *
- * <pre>import org.hibernate.SessionFactory
+ * <pre class="code">
+ * import org.hibernate.SessionFactory
  * import org.apache.commons.dbcp.BasicDataSource
  *
  * def reader = new GroovyBeanDefinitionReader(myApplicationContext)
@@ -81,11 +82,12 @@ import org.springframework.core.io.support.ResourcePatternUtils;
  *     }
  * }</pre>
  *
- * <p>You can also load resources containing beans defined as a Groovy script using
+ * <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:
  *
- * <pre>import org.hibernate.SessionFactory
+ * <pre class="code">
+ * import org.hibernate.SessionFactory
  * import org.apache.commons.dbcp.BasicDataSource
  *
  * beans {
@@ -257,10 +259,10 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * Defines an inner bean definition
-	 * @param type The bean type
-	 * @param args The constructors arguments and closure configurer
-	 * @return The bean definition
+	 * Define an inner bean definition.
+	 * @param type the bean type
+	 * @param args the constructors arguments and closure configurer
+	 * @return the bean definition
 	 */
 	public AbstractBeanDefinition bean(Class<?> type, Object...args) {
 		GroovyBeanDefinitionWrapper current = this.currentBeanDefinition;
@@ -292,7 +294,7 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * Defines an Spring namespace definition to use.
+	 * Define a Spring namespace definition to use.
 	 * @param definition the namespace definition
 	 */
 	public void xmlns(Map<String, String> definition) {
@@ -314,7 +316,8 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * Imports Spring bean definitions from either XML or Groovy sources into the current bean builder instance.
+	 * Import Spring bean definitions from either XML or Groovy sources into the
+	 * current bean builder instance.
 	 * @param resourcePattern the resource pattern
 	 */
 	public void importBeans(String resourcePattern) throws IOException {
@@ -336,7 +339,7 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 
 	/**
 	 * This method overrides method invocation to create beans for each method name that
-	 * takes a class argument
+	 * takes a class argument.
 	 */
 	public Object invokeMethod(String name, Object arg) {
 		Object[] args = (Object[])arg;
@@ -411,7 +414,7 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * When an methods argument is only a closure it is a set of bean definitions.
+	 * When a method argument is only a closure it is a set of bean definitions.
 	 * @param callable the closure argument
 	 * @return this GroovyBeanDefinitionReader instance
 	 */
@@ -528,7 +531,7 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * Checks whether there are any {@link RuntimeBeanReference} inside the Map
+	 * Checks whether there are any {@link RuntimeBeanReference}s inside the Map
 	 * and converts it to a ManagedMap if necessary.
 	 * @param map the original Map
 	 * @return either the original map or a managed copy of it
@@ -550,8 +553,8 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * Checks whether there are any {@link RuntimeBeanReference} inside the Lis
-	 * and  converts it to a ManagedList if necessary.
+	 * Checks whether there are any {@link RuntimeBeanReference}s inside the List
+	 * and converts it to a ManagedList if necessary.
 	 * @param list the original List
 	 * @return either the original list or a managed copy of it
 	 */
@@ -612,10 +615,14 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 	}
 
 	/**
-	 * This method overrides property retrieval in the scope of the GroovyBeanDefinitionReader to either:
-	 * a) Retrieve a variable from the bean builder's binding if it exists
-	 * b) Retrieve a RuntimeBeanReference for a specific bean if it exists
-	 * c) Otherwise just delegate to MetaClass.getProperty which will resolve properties from the GroovyBeanDefinitionReader itself
+	 * This method overrides property retrieval in the scope of the
+	 * 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
+	 * </ul>
 	 */
 	public Object getProperty(String name) {
 		Binding binding = getBinding();
@@ -678,9 +685,10 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 
 
 	/**
-	 * This class is used to defer the adding of a property to a bean definition until later
-	 * This is for a case where you assign a property to a list that may not contain bean references at
-	 * that point of assignment, but may later hence it would need to be managed
+	 * This class is used to defer the adding of a property to a bean definition
+	 * until later. This is for a case where you assign a property to a list that
+	 * may not contain bean references at that point of assignment, but may later;
+	 * hence, it would need to be managed.
 	 */
 	private static class DeferredProperty {
 
@@ -703,7 +711,7 @@ public class GroovyBeanDefinitionReader extends AbstractBeanDefinitionReader imp
 
 
 	/**
-	 * A RuntimeBeanReference that takes care of adding new properties to runtime references
+	 * A RuntimeBeanReference that takes care of adding new properties to runtime references.
 	 */
 	private class GroovyRuntimeBeanReference extends RuntimeBeanReference implements GroovyObject {
 
diff --git a/spring-context/src/main/java/org/springframework/context/support/GenericGroovyApplicationContext.java b/spring-context/src/main/java/org/springframework/context/support/GenericGroovyApplicationContext.java
index 157892feb8..ba54a71a49 100644
--- a/spring-context/src/main/java/org/springframework/context/support/GenericGroovyApplicationContext.java
+++ b/spring-context/src/main/java/org/springframework/context/support/GenericGroovyApplicationContext.java
@@ -36,9 +36,10 @@ import org.springframework.core.io.Resource;
  *
  * <p>Consider this as the equivalent of {@link GenericXmlApplicationContext} for
  * Groovy bean definitions. The main difference is that, within a Groovy script,
- * the context can be used with an inline bean definition closure like as follows:
+ * the context can be used with an inline bean definition closure as follows:
  *
- * <pre>import org.hibernate.SessionFactory
+ * <pre class="code">
+ * import org.hibernate.SessionFactory
  * import org.apache.commons.dbcp.BasicDataSource
  *
  * def context = new GenericGroovyApplicationContext()
@@ -59,12 +60,14 @@ import org.springframework.core.io.Resource;
  *         }
  *     }
  * }
- * context.refresh()</pre>
+ * context.refresh()
+ * </pre>
  *
  * <p>Alternatively, load a Groovy bean definition script like the following
  * from an external resource (e.g. an "applicationContext.groovy" file):
  *
- * <pre>import org.hibernate.SessionFactory
+ * <pre class="code">
+ * import org.hibernate.SessionFactory
  * import org.apache.commons.dbcp.BasicDataSource
  *
  * beans {
@@ -83,18 +86,23 @@ import org.springframework.core.io.Resource;
  *             dataSource = dataSource
  *         }
  *     }
- * }</pre>
+ * }
+ * </pre>
  *
  * <p>With the following Java code creating the {@code GenericGroovyApplicationContext}
  * (potentially using Ant-style '*'/'**' location patterns):
  *
- * <pre>GenericGroovyApplicationContext context = new GenericGroovyApplicationContext();
+ * <pre class="code">
+ * GenericGroovyApplicationContext context = new GenericGroovyApplicationContext();
  * context.load("org/myapp/applicationContext.groovy");
- * context.refresh();</pre>
+ * context.refresh();
+ * </pre>
  *
  * <p>Or even more concise, provided that no extra configuration is needed:
  *
- * <pre>ApplicationContext context = new GenericGroovyApplicationContext("org/myapp/applicationContext.groovy");</pre>
+ * <pre class="code">
+ * ApplicationContext context = new GenericGroovyApplicationContext("org/myapp/applicationContext.groovy");
+ * </pre>
  *
  * @author Juergen Hoeller
  * @author Jeff Brown