Clarify and log that return value of HandlerMethod is ignored if reason of @ResponseStatus present

spring-web/src/main/java/org/springframework/web/bind/annotation/ResponseStatus.java

@@ -80,7 +80,8 @@
 	/**
 	 * The <em>reason</em> to be used for the response.
 	 * <p>Defaults to an empty string which will be ignored. Set the reason to a
-	 * non-empty value to have it used for the response.
+	 * non-empty value to have it used for the response, please note that
+	 * return value of the annotated method will be ignored in this case.
 	 * @see jakarta.servlet.http.HttpServletResponse#sendError(int, String)
 	 */
 	String reason() default "";

spring-web/src/main/java/org/springframework/web/method/HandlerMethod.java

@@ -215,6 +215,9 @@ private void evaluateResponseStatus() {
 
 			this.responseStatus = annotation.code();
 			this.responseStatusReason = resolvedReason;
+			if (StringUtils.hasText(this.responseStatusReason) && getMethod().getReturnType() != void.class) {
+				logger.warn("Return value of method [" + getMethod() + "] will be ignored since reason of @ResponseStatus present, please consider changing the return type to void");
+			}
 		}
 	}
 

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/ServletInvocableHandlerMethod.java

@@ -126,6 +126,9 @@ public void invokeAndHandle(ServletWebRequest webRequest, ModelAndViewContainer
 			}
 		}
 		else if (StringUtils.hasText(getResponseStatusReason())) {
+			if (logger.isDebugEnabled()) {
+				logger.debug("Return value [" + returnValue + "] of method [" + getMethod() + "] is ignored since reason of @ResponseStatus will be used for response");
+			}
 			mavContainer.setRequestHandled(true);
 			return;
 		}