diff --git a/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/Param.java b/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/Param.java
index b0adb36dddb..0dfa4b24bfd 100644
--- a/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/Param.java
+++ b/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/Param.java
@@ -20,6 +20,9 @@ package org.springframework.web.servlet.tags;
  * Bean used to pass name-value pair parameters from a {@link ParamTag} to a
  * {@link ParamAware} tag.
  * 
+ * <p>Attributes are the raw values passed to the spring:param tag and have not 
+ * been encoded or escaped. 
+ * 
  * @author Scott Andrews
  * @since 3.0
  * @see ParamTag
@@ -31,28 +34,28 @@ public class Param {
 	private String value;
 
 	/**
-	 * @return the non-encoded parameter name
+	 * @return the raw parameter name
 	 */
 	public String getName() {
 		return name;
 	}
 
 	/**
-	 * Set the non-encoded name of the parameter
+	 * Set the raw name of the parameter
 	 */
 	public void setName(String name) {
 		this.name = name;
 	}
 
 	/**
-	 * @return the non-encoded parameter value
+	 * @return the raw parameter value
 	 */
 	public String getValue() {
 		return value;
 	}
 
 	/**
-	 * Set the non-encoded value of the parameter
+	 * Set the raw value of the parameter
 	 */
 	public void setValue(String value) {
 		this.value = value;
diff --git a/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/ParamTag.java b/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/ParamTag.java
index 055c437344d..3d085074017 100644
--- a/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/ParamTag.java
+++ b/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/ParamTag.java
@@ -23,8 +23,7 @@ import javax.servlet.jsp.tagext.BodyTagSupport;
  * JSP tag for collecting name-value parameters and passing them to a
  * {@link ParamAware} ancestor in the tag hierarchy.
  * 
- * <p>
- * This tag must be nested under a param aware tag.
+ * <p>This tag must be nested under a param aware tag.
  * 
  * @author Scott Andrews
  * @since 3.0
diff --git a/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/UrlTag.java b/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/UrlTag.java
index fb60775f038..fd92db6686f 100644
--- a/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/UrlTag.java
+++ b/org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/tags/UrlTag.java
@@ -37,26 +37,33 @@ import org.springframework.web.util.TagUtils;
  * JSP tag for creating URLs. Modeled after the JSTL c:url tag with backwards
  * compatibility in mind.
  * 
- * <p>
- * Enhancements to the JSTL functionality include:
+ * <p>Enhancements to the JSTL functionality include:
  * <ul>
  * <li>URL encoded template URI variables</li>
- * <li>Server and servlet relative URLs in addition to the standard context
- * relative.</li>
  * <li>XML escaping of URLs</li>
  * </ul>
  * 
- * <p>
- * Template URI variables are indicated in the {@link #setValue(String) 'value'}
- * attribute and marked by braces '{}'. The braces and attribute name are
- * replaced by the URL encoded value of a parameter. If no parameter is
- * available the literal value is passed through. Params matched to template
- * variables will not be added to the query string.
+ * <p>Template URI variables are indicated in the {@link #setValue(String) 'value'}
+ * attribute and marked by braces '{variableName}'. The braces and attribute name are
+ * replaced by the URL encoded value of a parameter defined with the spring:param tag 
+ * in the body of the url tag. If no parameter is available the literal value is 
+ * passed through. Params matched to template variables will not be added to the query 
+ * string.
  * 
- * <p>
- * URLs can be XML escaped by setting the {@link #setEscapeXml(String) 
+ * <p>Use of the spring:param tag for URI template variables is strongly recommended 
+ * over direct EL substitution as the values are URL encoded.  Failure to properly 
+ * encode URL can leave an application vulnerable to XSS and other injection attacks.
+ * 
+ * <p>URLs can be XML escaped by setting the {@link #setEscapeXml(String) 
  * 'escapeXml'} attribute to 'true', the default is 'false'.
  * 
+ * <p>Example usage:
+ * <pre>&lt;spring:url value="/url/path/{variableName}"&gt;
+ *   &lt;spring:param name="variableName" value="more than JSTL c:url" /&gt;
+ * &lt;/spring:url&gt;</pre>
+ * Results in:
+ * <code>/currentApplicationContext/url/path/more+than+JSTL+c%3Aurl</code>
+ * 
  * @author Scott Andrews
  * @since 3.0
  * @see ParamTag
diff --git a/org.springframework.web.servlet/src/main/resources/META-INF/spring.tld b/org.springframework.web.servlet/src/main/resources/META-INF/spring.tld
index a0bb87c7c8a..85ae51afd32 100644
--- a/org.springframework.web.servlet/src/main/resources/META-INF/spring.tld
+++ b/org.springframework.web.servlet/src/main/resources/META-INF/spring.tld
@@ -385,7 +385,7 @@
 			<description>Escape XML special characters in the resulting URL.  'true' and 
 			'false' are supported.  Defaults to 'false' to maintain compatibility with 
 			the JSTL c:url tag.  Strongly recommended to set as 'true' when rendering 
-			directly to the JspWriter in an XML or HTML based file.</description>
+			directly to the JspWriter in an XML or HTML based document.</description>
 		</attribute>
 	</tag>