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
  */