Update Javadoc for WebClient onStatus handlers

Closes gh-24736

Author: rstoyanchev

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -197,9 +197,9 @@ public interface ClientResponse {
 	Mono<ResponseEntity<Void>> toBodilessEntity();
 
 	/**
-	 * Creates a {@link WebClientResponseException} based on the status code,
-	 * headers, and body of this response as well as the corresponding request.
-	 * @return a {@code Mono} with a {@code WebClientResponseException} based on this response
+	 * Create a {@link WebClientResponseException} that contains the response
+	 * status, headers, body, and the originating request.
+	 * @return a {@code Mono} with the created exception
 	 * @since 5.2
 	 */
 	Mono<WebClientResponseException> createException();

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

@@ -650,38 +650,39 @@ <T, P extends Publisher<T>> RequestHeadersSpec<?> body(P publisher,
 	interface ResponseSpec {
 
 		/**
-		 * Register a custom error function that gets invoked when the given {@link HttpStatus}
-		 * predicate applies. Whatever exception is returned from the function (possibly using
-		 * {@link ClientResponse#createException()}) will also be returned as error signal
-		 * from {@link #bodyToMono(Class)} and {@link #bodyToFlux(Class)}.
-		 * <p>By default, an error handler is registered that returns a
-		 * {@link WebClientResponseException} when the response status code is 4xx or 5xx.
-		 * To override this default (and return a non-error response from {@code bodyOn*}), register
-		 * an exception function that returns an {@linkplain Mono#empty() empty} mono.
-		 * <p><strong>NOTE:</strong> if the response is expected to have content,
-		 * the exceptionFunction should consume it. If not, the content will be
-		 * automatically drained to ensure resources are released.
-		 * @param statusPredicate a predicate that indicates whether {@code exceptionFunction}
-		 * applies
-		 * @param exceptionFunction the function that returns the exception
+		 * Provide a function to map specific error status codes to an error
+		 * signal to to be propagated downstream instead of the response.
+		 * <p>By default, if there are not matching status handlers, responses
+		 * with status codes >= 400 are mapped to
+		 * {@link WebClientResponseException} which is created with
+		 * {@link ClientResponse#createException()}.
+		 * <p>To suppress the treatment of a status code as an error and process
+		 * it as a normal response, return {@code Mono.empty()} from the function.
+		 * The response will then propagate downstream for processing.
+		 * <p>To ignore an error response, handle it earlier with a
+		 * {@link ExchangeFilterFunction filter}, or add {@code onErrorResume}
+		 * downstream, for example:
+		 * <pre class="code">
+		 * webClient.get()
+		 *     .uri("http://abc.com/account/123")
+		 *     .retrieve()
+		 *     .bodyToMono(Account.class)
+		 *     .onErrorResume(WebClientResponseException.class,
+		 *          ex -> ex.getRawStatusCode() == 404 ? Mono.empty() : Mono.error(ex));
+		 * </pre>
+		 * @param statusPredicate to match responses with
+		 * @param exceptionFunction to map the response to an error signal
 		 * @return this builder
 		 * @see ClientResponse#createException()
 		 */
 		ResponseSpec onStatus(Predicate<HttpStatus> statusPredicate,
 				Function<ClientResponse, Mono<? extends Throwable>> exceptionFunction);
 
 		/**
-		 * Register a custom error function that gets invoked when the given raw status code
-		 * predicate applies. The exception returned from the function will be returned from
-		 * {@link #bodyToMono(Class)} and {@link #bodyToFlux(Class)}.
-		 * <p>By default, an error handler is registered that throws a
-		 * {@link WebClientResponseException} when the response status code is 4xx or 5xx.
-		 * @param statusCodePredicate a predicate of the raw status code that indicates
-		 * whether {@code exceptionFunction} applies.
-		 * <p><strong>NOTE:</strong> if the response is expected to have content,
-		 * the exceptionFunction should consume it. If not, the content will be
-		 * automatically drained to ensure resources are released.
-		 * @param exceptionFunction the function that returns the exception
+		 * Variant of {@link #onStatus(Predicate, Function)} that works with
+		 * raw status code values. This is useful for custom status codes.
+		 * @param statusCodePredicate to match responses with
+		 * @param exceptionFunction to map the response to an error signal
 		 * @return this builder
 		 * @since 5.1.9
 		 */