Update documentation for Map arguments

Issue: SPR-12347

Author: rstoyanchev

spring-web/src/main/java/org/springframework/web/bind/annotation/MatrixVariable.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -27,6 +27,15 @@
  * name-value pair within a path segment. Supported for {@link RequestMapping}
  * annotated handler methods in Servlet environments.
  *
+ * <p>If the method parameter type is {@link java.util.Map} and a matrix variable
+ * name is specified, then the matrix variable value is converted to a
+ * {@link java.util.Map} assuming an appropriate conversion strategy is available.
+ *
+ * <p>If the method parameter is {@link java.util.Map Map&lt;String, String&gt;} or
+ * {@link org.springframework.util.MultiValueMap MultiValueMap&lt;String, String&gt;}
+ * and a variable name is not specified, then the map is populated with all
+ * matrix variable names and values.
+ *
  * @author Rossen Stoyanchev
  * @since 3.2
  */

spring-web/src/main/java/org/springframework/web/bind/annotation/PathVariable.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -27,6 +27,10 @@
  * variable. Supported for {@link RequestMapping} annotated handler methods in Servlet
  * environments.
  *
+ * <p>If the method parameter is {@link java.util.Map Map&lt;String, String&gt;} or
+ * {@link org.springframework.util.MultiValueMap MultiValueMap&lt;String, String&gt;}
+ * then the map is populated with all path variable names and values.
+ *
  * @author Arjen Poutsma
  * @since 3.0
  * @see RequestMapping

spring-web/src/main/java/org/springframework/web/bind/annotation/RequestHeader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -26,6 +26,11 @@
  * Annotation which indicates that a method parameter should be bound to a web request header.
  * Supported for annotated handler methods in Servlet and Portlet environments.
  *
+ * <p>If the method parameter is {@link java.util.Map Map&lt;String, String&gt;} or
+ * {@link org.springframework.util.MultiValueMap MultiValueMap&lt;String, String&gt;},
+ * or {@link org.springframework.http.HttpHeaders HttpHeaders} then the map is
+ * populated with all header names and values.
+ *
  * @author Juergen Hoeller
  * @since 3.0
  * @see RequestMapping

src/asciidoc/index.adoc

@@ -30829,6 +30829,7 @@ multiple requests are allowed to access a session concurrently.
   <<mvc-ann-requestparam>>.
 * `@RequestHeader` annotated parameters for access to specific Servlet request HTTP
   headers. Parameter values are converted to the declared method argument type.
+  See <<mvc-ann-requestheader>>.
 * `@RequestBody` annotated parameters for access to the HTTP request body. Parameter
   values are converted to the declared method argument type using
   ++HttpMessageConverter++s. See <<mvc-ann-requestbody>>.
@@ -30968,6 +30969,10 @@ parameter is optional by setting ++@RequestParam++'s `required` attribute to `fa
 Type conversion is applied automatically if the target method parameter type is not
 `String`. See <<mvc-ann-typeconversion>>.
 
+When an `@RequestParam` annotation is used on a `Map<String, String>` or
+`MultiValueMap<String, String>` argument, the map is populated with all request
+parameters.
+
 
 [[mvc-ann-requestbody]]
 ===== Mapping the request body with the @RequestBody annotation
@@ -31471,6 +31476,11 @@ The following code sample demonstrates how to get the value of the `Accept-Encod
 Type conversion is applied automatically if the method parameter is not `String`. See
 <<mvc-ann-typeconversion>>.
 
+When an `@RequestHeader` annotation is used on a `Map<String, String>`,
+`MultiValueMap<String, String>`, or `HttpHeaders` argument, the map is populated
+with all header values.
+
+
 [TIP]
 ====
 Built-in support is available for converting a comma-separated string into an