INT-656 javadoc update

org.springframework.integration/src/main/java/org/springframework/integration/message/MethodParameterMessageMapper.java

@@ -41,27 +41,35 @@ import org.springframework.util.StringUtils;
 
 /**
  * Prepares arguments for handler methods. The method parameters are matched
- * against the Message, its payload as well as its headers. A message or payload
- * parameter must not be annotated, there can be at most one of these. In
- * certain special cases more than one unannotated parameters can be used (more
- * on this later) but there should always be at most one parameter that the
- * message or it's payload.
+ * against the Message, its payload as well as its headers. A message or
+ * payload parameter must not be annotated, and there can be at most one of
+ * these. In certain special cases, more than one non-annotated parameter can
+ * be used (more on this later), but there should always be at most one
+ * parameter that is expecting the message or its payload.
  * <p/>
  * If a method parameter is annotated with {@link Header @Header}, the
  * annotation's value will be used as a header name. If such an annotation
  * contains no value, then the parameter name will be used as long as the
  * information is available in the class file (requires compilation with debug
- * settings for parameter names). In addition a Map or Properties parameter can
- * be matched to all the message headers. This can be done explicitly through
- * the {@link Headers @Headers} annotation, or implicitly by using a non
- * ambiguous method signature. There can be as many Header annotated parameters
- * as the user wants. There needs to be only one Headers parameter.
+ * settings for parameter names).
+ * <p/>
+ * In addition a Map or Properties parameter can receive multiple message
+ * headers. In the case of a Map argument, all headers will be passed, but in
+ * the case of a Properties argument, only the headers with String-typed values
+ * will be passed. These parameters can be labeled explicitly with the
+ * {@link Headers @Headers} annotation, or matched implicitly by using a non-
+ * ambiguous method signature. There can be as many parameters annotated with
+ * @Header as necessary, but typically there should be only one parameter
+ * expecting multiple headers (with or without the @Headers annotation).
  * <p/>
  * If a Map or Properties object is expected, and the payload is not itself
  * assignable to that type, then the MessageHeaders' values will be passed in
  * the case of a Map-typed parameter, or the MessageHeaders' String-based values
  * will be passed in the case of a Properties-typed parameter. In these cases
- * multiple unannotated parameters are legal.
+ * multiple unannotated parameters are legal. If, however, the actual payload
+ * type is a Map or Properties instance, then this ambiguity cannot be
+ * resolved. For that reason, it is recommended to use the explicit
+ * {@link Headers @Headers} annotation whenever possible.
  * <p/>
  * Some examples of legal method signatures:<br/>
  * <tt>public void dealWith(Object payload);</tt><br/>