From af2e296ff307287b29ae3361b898bc73b73e7b55 Mon Sep 17 00:00:00 2001
From: Arjen Poutsma <apoutsma@pivotal.io>
Date: Mon, 6 Nov 2017 16:00:18 +0100
Subject: [PATCH] Javadoc

---
 .../http/client/MultipartBodyBuilder.java     |  4 +--
 .../web/client/RestOperations.java            | 36 ++++++++++++++-----
 .../web/reactive/function/BodyInserters.java  | 11 ++++--
 3 files changed, 36 insertions(+), 15 deletions(-)

diff --git a/spring-web/src/main/java/org/springframework/http/client/MultipartBodyBuilder.java b/spring-web/src/main/java/org/springframework/http/client/MultipartBodyBuilder.java
index 7b46725b788..593020037ce 100644
--- a/spring-web/src/main/java/org/springframework/http/client/MultipartBodyBuilder.java
+++ b/spring-web/src/main/java/org/springframework/http/client/MultipartBodyBuilder.java
@@ -33,9 +33,7 @@ import org.springframework.util.MultiValueMap;
  * <pre class="code">
  *
  * MultipartBodyBuilder builder = new MultipartBodyBuilder();
- * MultiValueMap&lt;String, String&gt; form = new LinkedMultiValueMap&lt;&gt;();
- * form.add("form field", "form value");
- * builder.part("form", form).header("Foo", "Bar");
+ * builder.part("form field", "form value");
  *
  * Resource image = new ClassPathResource("image.jpg");
  * builder.part("image", image).header("Baz", "Qux");
diff --git a/spring-web/src/main/java/org/springframework/web/client/RestOperations.java b/spring-web/src/main/java/org/springframework/web/client/RestOperations.java
index 9cfac8356ce..2a0ad672416 100644
--- a/spring-web/src/main/java/org/springframework/web/client/RestOperations.java
+++ b/spring-web/src/main/java/org/springframework/web/client/RestOperations.java
@@ -149,7 +149,9 @@ public interface RestOperations {
 	 * the {@code Location} header. This header typically indicates where the new resource is stored.
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request.
+	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
+	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
+	 * simulate a multipart from submission.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
@@ -164,7 +166,9 @@ public interface RestOperations {
 	 * the {@code Location} header. This header typically indicates where the new resource is stored.
 	 * <p>URI Template variables are expanded using the given map.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request.
+	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
+	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
+	 * simulate a multipart from submission.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
@@ -179,7 +183,9 @@ public interface RestOperations {
 	 * Create a new resource by POSTing the given object to the URL, and returns the value of the
 	 * {@code Location} header. This header typically indicates where the new resource is stored.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request.
+	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
+ 	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
+ 	 * simulate a multipart from submission.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @return the value for the {@code Location} header
@@ -193,7 +199,9 @@ public interface RestOperations {
 	 * and returns the representation found in the response.
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request.
+	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
+ 	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
+ 	 * simulate a multipart from submission.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
@@ -210,7 +218,9 @@ public interface RestOperations {
 	 * and returns the representation found in the response.
 	 * <p>URI Template variables are expanded using the given map.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request.
+	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
+	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
+ 	 * simulate a multipart from submission.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
@@ -226,7 +236,9 @@ public interface RestOperations {
 	 * Create a new resource by POSTing the given object to the URL,
 	 * and returns the representation found in the response.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request.
+	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
+ 	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
+ 	 * simulate a multipart from submission.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
@@ -241,7 +253,9 @@ public interface RestOperations {
 	 * and returns the response as {@link ResponseEntity}.
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request.
+	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
+	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
+	 * simulate a multipart from submission.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
@@ -257,7 +271,9 @@ public interface RestOperations {
 	 * and returns the response as {@link HttpEntity}.
 	 * <p>URI Template variables are expanded using the given map.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request.
+	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
+ 	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
+ 	 * simulate a multipart from submission.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
@@ -272,7 +288,9 @@ public interface RestOperations {
 	 * Create a new resource by POSTing the given object to the URL,
 	 * and returns the response as {@link ResponseEntity}.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request.
+	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
+ 	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
+ 	 * simulate a multipart from submission.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @return the converted object
diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/function/BodyInserters.java b/spring-webflux/src/main/java/org/springframework/web/reactive/function/BodyInserters.java
index ab9f65e77b6..902319a9d6a 100644
--- a/spring-webflux/src/main/java/org/springframework/web/reactive/function/BodyInserters.java
+++ b/spring-webflux/src/main/java/org/springframework/web/reactive/function/BodyInserters.java
@@ -220,7 +220,9 @@ public abstract class BodyInserters {
 
 	/**
 	 * Return a {@code FormInserter} that writes the given {@code MultiValueMap}
-	 * as multipart data. Note that the returned inserter allows for additional entries to be added
+	 * as multipart data. The {@code multipartData} parameter can conveniently be built using the
+	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
+	 * Note that the returned inserter allows for additional entries to be added
 	 * via {@link FormInserter#with(String, Object)}.
 	 *
 	 * <p><strong>Note:</strong> you can also use the {@code syncBody(Object)}
@@ -243,8 +245,11 @@ public abstract class BodyInserters {
 	}
 
 	/**
-	 * Return a {@code FormInserter} that writes the key-value pair  as multipart data. Note that
-	 * the returned inserter allows for additional entries to be added via
+	 * Return a {@code FormInserter} that writes the key-value pair  as multipart data. The
+	 * {@code multipartData} parameter can conveniently be built using the
+	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
+	 * Note that the returned inserter allows for additional entries to be added
+	 * via {@link FormInserter#with(String, Object)}.
 	 * {@link FormInserter#with(String, Object)}.
 	 * @param key the key to add to the form
 	 * @param value the value to add to the form