Links from @RequestMapping to reference docs

Issue: SPR-16266

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

@@ -25,21 +25,33 @@ import java.lang.annotation.Target;
 import org.springframework.core.annotation.AliasFor;
 
 /**
- * Annotation for mapping web requests onto specific handler classes and/or
- * handler methods.
+ * Annotation for mapping web requests onto methods in request-handling classes
+ * with flexible method signatures.
  *
- * <p>Handler methods annotated with this annotation can have very flexible
- * signatures. The exact details of the supported method arguments and return
- * values depend on the specific
- * {@link org.springframework.stereotype.Controller @Controller} model supported.
- * Both Spring Web MVC and Spring WebFlux support this annotation with some
- * differences. More details are available in the Spring Framework reference.
+ * <p>Both Spring MVC and Spring WebFlux support this annotation through a
+ * {@code RequestMappingHandlerMapping} and {@code RequestMappingHandlerAdapter}
+ * in their respective modules and package structure. For the exact list of
+ * supported handler method arguments and return types in each, please use the
+ * reference documentation links below:
+ * <ul>
+ * <li>Spring MVC
+ * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-ann-arguments">Method Arguments</a>
+ * and
+ * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#mvc-ann-return-types">Return Values</a>
+ * </li>
+ * <li>Spring WebFlux
+ * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html#webflux-ann-arguments">Method Arguments</a>
+ * and
+ * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html#webflux-ann-return-types">Return Values</a>
+ * </li>
+ * </ul>
  *
- * <p><b>NOTE:</b> {@code @RequestMapping} will only be processed if an
- * an appropriate {@code HandlerMapping}-{@code HandlerAdapter} pair
- * is configured. If you are defining custom {@code HandlerMappings} or
- * {@code HandlerAdapters}, then you need to add {@code RequestMappingHandlerMapping}
- * and {@code RequestMappingHandlerAdapter} to your configuration.</code>.
+ * <p><strong>Note:</strong> This annotation can be used both at the class and
+ * at the method level. In most cases, at the method level applications will
+ * prefer to use one of the HTTP method specific variants
+ * {@link GetMapping @GetMapping}, {@link PostMapping @PostMapping},
+ * {@link PutMapping @PutMapping}, {@link DeleteMapping @DeleteMapping}, or
+ * {@link PatchMapping @PatchMapping}.</p>
  *
  * <p><b>NOTE:</b> When using controller interfaces (e.g. for AOP proxying),
  * make sure to consistently put <i>all</i> your mapping annotations - such as
@@ -55,13 +67,6 @@ import org.springframework.core.annotation.AliasFor;
  * @see PutMapping
  * @see DeleteMapping
  * @see PatchMapping
- * @see RequestParam
- * @see RequestAttribute
- * @see PathVariable
- * @see ModelAttribute
- * @see SessionAttribute
- * @see SessionAttributes
- * @see InitBinder
  * @see org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter
  * @see org.springframework.web.reactive.result.method.annotation.RequestMappingHandlerAdapter
  */

spring-webflux/src/main/java/org/springframework/web/reactive/result/method/annotation/RequestMappingHandlerAdapter.java

@@ -43,7 +43,9 @@ import org.springframework.web.reactive.result.method.InvocableHandlerMethod;
 import org.springframework.web.server.ServerWebExchange;
 
 /**
- * Supports the invocation of {@code @RequestMapping} methods.
+ * Supports the invocation of
+ * {@link org.springframework.web.bind.annotation.RequestMapping @RequestMapping}
+ * handler methods.
  *
  * @author Rossen Stoyanchev
  * @since 5.0

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

@@ -98,13 +98,12 @@ import org.springframework.web.servlet.support.RequestContextUtils;
 import org.springframework.web.util.WebUtils;
 
 /**
- * An {@link AbstractHandlerMethodAdapter} that supports {@link HandlerMethod}s
- * with their method argument and return type signature, as defined via
- * {@code @RequestMapping}.
+ * Extension of {@link AbstractHandlerMethodAdapter} that supports
+ * {@link RequestMapping} annotated {@code HandlerMethod}s.
  *
  * <p>Support for custom argument and return value types can be added via
- * {@link #setCustomArgumentResolvers} and {@link #setCustomReturnValueHandlers}.
- * Or alternatively, to re-configure all argument and return value types,
+ * {@link #setCustomArgumentResolvers} and {@link #setCustomReturnValueHandlers},
+ * or alternatively, to re-configure all argument and return value types,
  * use {@link #setArgumentResolvers} and {@link #setReturnValueHandlers}.
  *
  * @author Rossen Stoyanchev