Refine validation section for controllers

Closes gh-35759

Author: rstoyanchev

framework-docs/modules/ROOT/pages/web/webflux/controller/ann-validation.adoc

@@ -7,19 +7,23 @@ Spring WebFlux has built-in xref:core/validation/validator.adoc[Validation] for
 `@RequestMapping` methods, including xref:core/validation/beanvalidation.adoc[Java Bean Validation].
 Validation may be applied at one of two levels:
 
-1. xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[@ModelAttribute],
+1. Java Bean Validation is applied individually to an
+xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[@ModelAttribute],
 xref:web/webflux/controller/ann-methods/requestbody.adoc[@RequestBody], and
-xref:web/webflux/controller/ann-methods/multipart-forms.adoc[@RequestPart] argument
-resolvers validate a method argument individually if the method parameter is annotated
-with Jakarta `@Valid` or Spring's `@Validated`, _AND_ there is no `Errors` or
-`BindingResult` parameter immediately after, _AND_ method validation is not needed (to be
-discussed next). The exception raised in this case is `WebExchangeBindException`.
-
-2. When `@Constraint` annotations such as `@Min`, `@NotBlank` and others are declared
-directly on method parameters, or on the method (for the return value), then method
-validation must be applied, and that supersedes validation at the method argument level
-because method validation covers both method parameter constraints and nested constraints
-via `@Valid`. The exception raised in this case is `HandlerMethodValidationException`.
+xref:web/webflux/controller/ann-methods/multipart-forms.adoc[@RequestPart] method parameter
+annotated with `@jakarta.validation.Valid` or Spring's `@Validated` so long as
+it is a command object rather than a container such as `Map` or `Collection`, it does not
+have `Errors` or `BindingResult` immediately after in the method signature, and does not
+otherwise require method validation (see next). `WebExchangeBindException` is the
+exception raised when validating a method parameter individually.
+
+2. Java Bean Validation is applied to the method when `@Constraint` annotations such as
+`@Min`, `@NotBlank` and others are declared directly on method parameters, or on the
+method for the return value, and it supersedes any validation that would be applied
+otherwise to a method parameter individually because method validation covers both
+method parameter constraints and nested constraints via `@Valid`.
+`HandlerMethodValidationException` is the exception raised validation is applied
+to the method.
 
 Applications must handle both `WebExchangeBindException` and
 `HandlerMethodValidationException` as either may be raised depending on the controller

framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-validation.adoc

@@ -7,22 +7,26 @@ Spring MVC has built-in xref:core/validation/validator.adoc[validation] for
 `@RequestMapping` methods, including xref:core/validation/beanvalidation.adoc[Java Bean Validation].
 Validation may be applied at one of two levels:
 
-1. xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[@ModelAttribute],
+1. Java Bean Validation is applied individually to an
+xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[@ModelAttribute],
 xref:web/webmvc/mvc-controller/ann-methods/requestbody.adoc[@RequestBody], and
-xref:web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc[@RequestPart] argument
-resolvers validate a method argument individually if the method parameter is annotated
-with Jakarta `@Valid` or Spring's `@Validated`, _AND_ there is no `Errors` or
-`BindingResult` parameter immediately after, _AND_ method validation is not needed (to be
-discussed next). The exception raised in this case is `MethodArgumentNotValidException`.
-
-2. When `@Constraint` annotations such as `@Min`, `@NotBlank` and others are declared
-directly on method parameters, or on the method (for the return value), then method
-validation must be applied, and that supersedes validation at the method argument level
-because method validation covers both method parameter constraints and nested constraints
-via `@Valid`. The exception raised in this case is `HandlerMethodValidationException`.
-
-Applications must handle both `MethodArgumentNotValidException` and
-`HandlerMethodValidationException` as either may be raised depending on the controller
+xref:web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc[@RequestPart] method parameter
+annotated with `@jakarta.validation.Valid` or Spring's `@Validated` so long as
+it is a command object rather than a container such as `Map` or `Collection`, it does not
+have `Errors` or `BindingResult` immediately after in the method signature, and does not
+otherwise require method validation (see next). `MethodArgumentNotValidException` is the
+exception raised when validating a method parameter individually.
+
+2. Java Bean Validation is applied to the method when `@Constraint` annotations such as
+`@Min`, `@NotBlank` and others are declared directly on method parameters, or on the
+method for the return value, and it supersedes any validation that would be applied
+otherwise to a method parameter individually because method validation covers both
+method parameter constraints and nested constraints via `@Valid`.
+`HandlerMethodValidationException` is the exception raised validation is applied
+to the method.
+
+Applications should handle both `MethodArgumentNotValidException` and
+`HandlerMethodValidationException` since either may be raised depending on the controller
 method signature. The two exceptions, however are designed to be very similar, and can be
 handled with almost identical code. The main difference is that the former is for a single
 object while the latter is for a list of method parameters.