Warning against split URL handling in docs

Closes gh-24304

Author: rstoyanchev

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ViewControllerRegistry.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 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.
@@ -61,6 +61,10 @@ public ViewControllerRegistry(@Nullable ApplicationContext applicationContext) {
 	 * <p>Patterns like {@code "/admin/**"} or {@code "/articles/{articlename:\\w+}"}
 	 * are allowed. See {@link org.springframework.util.AntPathMatcher} for more details on the
 	 * syntax.
+	 * <p><strong>Note:</strong> If an {@code @RequestMapping} method is mapped
+	 * to a URL for any HTTP method then a view controller cannot handle the
+	 * same URL. For this reason it is recommended to avoid splitting URL
+	 * handling across an annotated controller and a view controller.
 	 */
 	public ViewControllerRegistration addViewController(String urlPath) {
 		ViewControllerRegistration registration = new ViewControllerRegistration(urlPath);

src/docs/asciidoc/web/webmvc.adoc

@@ -5399,6 +5399,13 @@ using the `<mvc:view-controller>` element:
 	<mvc:view-controller path="/" view-name="home"/>
 ----
 
+If an `@RequestMapping` method is mapped to a URL for any HTTP method then a view
+controller cannot be used to handle the same URL. This is because a match by URL to an
+annotated controller is considered a strong enough indication of endpoint ownership so
+that a 405 (METHOD_NOT_ALLOWED), a 415 (UNSUPPORTED_MEDIA_TYPE), or similar response can
+be sent to the client to help with debugging. For this reason it is recommended to avoid
+splitting URL handling across an annotated controller and a view controller.
+
 
 
 [[mvc-config-view-resolvers]]