Consistent JSP tag documentation

Issue: SPR-13520

Author: jhoeller

spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ArgumentAware.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 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.
@@ -33,4 +33,5 @@ public interface ArgumentAware {
 	 * @param argument the result of the nested {@code spring:argument} tag
 	 */
 	void addArgument(Object argument) throws JspTagException;
+
 }

spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ArgumentTag.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 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.
@@ -20,8 +20,8 @@
 import javax.servlet.jsp.tagext.BodyTagSupport;
 
 /**
- * JSP tag for collecting arguments and passing them to an {@link ArgumentAware} ancestor
- * in the tag hierarchy.
+ * JSP tag for collecting arguments and passing them to an {@link ArgumentAware}
+ * ancestor in the tag hierarchy.
  *
  * <p>This tag must be nested under an argument aware tag.
  *
@@ -37,7 +37,17 @@ public class ArgumentTag extends BodyTagSupport {
 
 	private boolean valueSet;
 
-	// tag lifecycle
+
+	/**
+	 * Set the value of the argument (optional).
+	 * <pIf not set, the tag's body content will get evaluated.
+	 * @param value the parameter value
+	 */
+	public void setValue(Object value) {
+		this.value = value;
+		this.valueSet = true;
+	}
+
 
 	@Override
 	public int doEndTag() throws JspException {
@@ -46,38 +56,20 @@ public int doEndTag() throws JspException {
 			argument = this.value;
 		}
 		else if (getBodyContent() != null) {
-			// get the value from the tag body
+			// Get the value from the tag body
 			argument = getBodyContent().getString().trim();
 		}
 
-		// find a param aware ancestor
-		ArgumentAware argumentAwareTag = (ArgumentAware) findAncestorWithClass(this,
-				ArgumentAware.class);
+		// Find a param-aware ancestor
+		ArgumentAware argumentAwareTag = (ArgumentAware) findAncestorWithClass(this, ArgumentAware.class);
 		if (argumentAwareTag == null) {
-			throw new JspException(
-					"The argument tag must be a descendant of a tag that supports arguments");
+			throw new JspException("The argument tag must be a descendant of a tag that supports arguments");
 		}
-
 		argumentAwareTag.addArgument(argument);
 
 		return EVAL_PAGE;
 	}
 
-	// tag attribute mutators
-
-	/**
-	 * Sets the value of the argument
-	 *
-	 * <p>
-	 * Optional. If not set, the tag's body content is evaluated.
-	 *
-	 * @param value the parameter value
-	 */
-	public void setValue(Object value) {
-		this.value = value;
-		this.valueSet = true;
-	}
-
 	@Override
 	public void release() {
 		super.release();

spring-webmvc/src/main/java/org/springframework/web/servlet/tags/ParamTag.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 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.
@@ -40,7 +40,22 @@ public class ParamTag extends BodyTagSupport {
 
 	private boolean valueSet;
 
-	// tag lifecycle
+
+	/**
+	 * Set the name of the parameter (required).
+	 */
+	public void setName(String name) {
+		this.name = name;
+	}
+
+	/**
+	 * Set the value of the parameter (optional).
+	 */
+	public void setValue(String value) {
+		this.value = value;
+		this.valueSet = true;
+	}
+
 
 	@Override
 	public int doEndTag() throws JspException {
@@ -50,50 +65,21 @@ public int doEndTag() throws JspException {
 			param.setValue(this.value);
 		}
 		else if (getBodyContent() != null) {
-			// get the value from the tag body
+			// Get the value from the tag body
 			param.setValue(getBodyContent().getString().trim());
 		}
 
-		// find a param aware ancestor
-		ParamAware paramAwareTag = (ParamAware) findAncestorWithClass(this,
-				ParamAware.class);
+		// Find a param aware ancestor
+		ParamAware paramAwareTag = (ParamAware) findAncestorWithClass(this, ParamAware.class);
 		if (paramAwareTag == null) {
-			throw new JspException(
-					"The param tag must be a descendant of a tag that supports parameters");
+			throw new JspException("The param tag must be a descendant of a tag that supports parameters");
 		}
 
 		paramAwareTag.addParam(param);
 
 		return EVAL_PAGE;
 	}
 
-	// tag attribute accessors
-
-	/**
-	 * Sets the name of the parameter
-	 *
-	 * <p>
-	 * Required
-	 *
-	 * @param name the parameter name
-	 */
-	public void setName(String name) {
-		this.name = name;
-	}
-
-	/**
-	 * Sets the value of the parameter
-	 *
-	 * <p>
-	 * Optional. If not set, the tag's body content is evaluated
-	 *
-	 * @param value the parameter value
-	 */
-	public void setValue(String value) {
-		this.value = value;
-		this.valueSet = true;
-	}
-
 	@Override
 	public void release() {
 		super.release();

spring-webmvc/src/main/java/org/springframework/web/servlet/tags/form/FormTag.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.
@@ -194,15 +194,18 @@ protected String getAction() {
 	}
 
 	/**
-	 * Set the value of the '{@code action}' attribute.
+	 * Set the value of the '{@code action}' attribute through a value
+	 * that is to be appended to the current servlet path.
 	 * <p>May be a runtime expression.
+	 * @since 3.2.3
 	 */
-	public void setServletRelativeAction(String servletRelativeaction) {
-		this.servletRelativeAction = (servletRelativeaction != null ? servletRelativeaction : "");
+	public void setServletRelativeAction(String servletRelativeAction) {
+		this.servletRelativeAction = (servletRelativeAction != null ? servletRelativeAction : "");
 	}
 
 	/**
-	 * Get the value of the '{@code action}' attribute.
+	 * Get the servlet-relative value of the '{@code action}' attribute.
+	 * @since 3.2.3
 	 */
 	protected String getServletRelativeAction() {
 		return this.servletRelativeAction;
@@ -322,7 +325,19 @@ public void setMethodParam(String methodParam) {
 
 	/**
 	 * Get the name of the request param for non-browser supported HTTP methods.
+	 * @since 4.2.3
+	 */
+	@SuppressWarnings("deprecation")
+	protected String getMethodParam() {
+		return getMethodParameter();
+	}
+
+	/**
+	 * Get the name of the request param for non-browser supported HTTP methods.
+	 * @deprecated as of 4.2.3, in favor of {@link #getMethodParam()} which is
+	 * a proper pairing for {@link #setMethodParam(String)}
 	 */
+	@Deprecated
 	protected String getMethodParameter() {
 		return this.methodParam;
 	}
@@ -334,6 +349,7 @@ protected boolean isMethodBrowserSupported(String method) {
 		return ("get".equalsIgnoreCase(method) || "post".equalsIgnoreCase(method));
 	}
 
+
 	/**
 	 * Writes the opening part of the block	'{@code form}' tag and exposes
 	 * the form object name in the {@link javax.servlet.jsp.PageContext}.
@@ -359,7 +375,7 @@ protected int writeTagContent(TagWriter tagWriter) throws JspException {
 
 		if (!isMethodBrowserSupported(getMethod())) {
 			assertHttpMethod(getMethod());
-			String inputName = getMethodParameter();
+			String inputName = getMethodParam();
 			String inputType = "hidden";
 			tagWriter.startTag(INPUT_TAG);
 			writeOptionalAttribute(tagWriter, TYPE_ATTRIBUTE, inputType);