Update docs on ClientResponse

Issue: SPR-16200

Author: rstoyanchev

spring-webflux/src/main/java/org/springframework/web/reactive/function/client/ClientResponse.java

@@ -38,10 +38,14 @@
  * {@link ExchangeFunction}. Provides access to the response status and headers,
  * and also methods to consume the response body.
  *
- * <p><strong>NOTE:</strong> When given access to a {@link ClientResponse} you
- * must always use the response body or entity methods to ensure resources are
- * released and to avoid potential issues with HTTP connection pooling. If not
- * interested in the response body, use {@code "bodyToMono(Void.class)"}.
+ * <p><strong>NOTE:</strong> When given access to a {@link ClientResponse},
+ * through the {@code WebClient}
+ * {@link WebClient.RequestHeadersSpec#exchange() exchange()} method,
+ * you must always use one of the body or toEntity methods to ensure resources
+ * are released and avoid potential issues with HTTP connection pooling.
+ * You can use {@code bodyToMono(Void.class)} if no response content is
+ * expected. However keep in mind that if the response does have content, the
+ * connection will be closed and will not be placed back in the pool.
  *
  * @author Brian Clozel
  * @author Arjen Poutsma

spring-webflux/src/main/java/org/springframework/web/reactive/function/client/WebClient.java

@@ -483,10 +483,9 @@ interface RequestHeadersSpec<S extends RequestHeadersSpec<S>> {
 		 *     .exchange()
 		 *     .flatMapMany(response -> response.bodyToFlux(Person.class));
 		 * </pre>
-		 * <p><strong>NOTE:</strong> You must always use of the body or entity
-		 * methods on {@link ClientResponse} to ensure resources are released and
-		 * avoid potential issues with HTTP connection pooling. If not interested
-		 * in the response body, use {@code "bodyToMono(Void.class)"} to complete.
+		 * <p><strong>NOTE:</strong> You must always use one of the body or
+		 * entity methods of the response to ensure resources are released.
+		 * See {@link ClientResponse} for more details.
 		 * @return a {@code Mono} for the response
 		 * @see #retrieve()
 		 */

src/docs/asciidoc/web/webflux-webclient.adoc

@@ -99,10 +99,11 @@ Note that unlike `retrieve()`, with `exchange()` there are no automatic error si
 
 [CAUTION]
 ====
-When using `exchange()` you must always use any of the body or entity methods of
+When using `exchange()` you must always use any of the body or toEntity methods of
 `ClientResponse` to ensure resources are released and to avoid potential issues with HTTP
-connection pooling. If not interested in the response body use `bodyToMono(Void.class)`
-to complete.
+connection pooling. You can use `bodyToMono(Void.class)` if no response content is
+expected. However keep in mind that if the response does have content, the connection
+will be closed and will not be placed back in the pool.
 ====