diff --git a/spring-web/src/main/java/org/springframework/web/accept/ContentNegotiationManagerFactoryBean.java b/spring-web/src/main/java/org/springframework/web/accept/ContentNegotiationManagerFactoryBean.java
index 42f515914105..0d4a1f7dd838 100644
--- a/spring-web/src/main/java/org/springframework/web/accept/ContentNegotiationManagerFactoryBean.java
+++ b/spring-web/src/main/java/org/springframework/web/accept/ContentNegotiationManagerFactoryBean.java
@@ -85,15 +85,14 @@
* methods and set the exact strategies to use via
* {@link #setStrategies(List)}.
*
- *
Note: As of 5.2.4,
+ *
Deprecation Note: As of 5.2.4,
* {@link #setFavorPathExtension(boolean) favorPathExtension} and
* {@link #setIgnoreUnknownPathExtensions(boolean) ignoreUnknownPathExtensions}
- * are deprecated in order to discourage use of path extensions for content
- * negotiation as well as for request mapping (with similar deprecations in
+ * are deprecated in order to discourage using path extensions for content
+ * negotiation and for request mapping with similar deprecations on
* {@link org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping
- * RequestMappingHandlerMapping}). For further context, please read issue
+ * RequestMappingHandlerMapping}. For further context, please read issue
* #24719.
- *
* @author Rossen Stoyanchev
* @author Brian Clozel
* @since 3.2
@@ -149,7 +148,10 @@ public void setStrategies(@Nullable List strategies)
* for {@code /hotels.pdf} will be interpreted as a request for
* {@code "application/pdf"} regardless of the 'Accept' header.
* @deprecated as of 5.2.4. See class-level note on the deprecation of path
- * extension config options.
+ * extension config options. As there is no replacement for this method,
+ * for the time being it's necessary to continue using it in order to set it
+ * to {@code false}. In 5.3 when {@code false} becomes the default, use of
+ * this property will no longer be necessary.
*/
@Deprecated
public void setFavorPathExtension(boolean favorPathExtension) {
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ContentNegotiationConfigurer.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ContentNegotiationConfigurer.java
index b1ce0732555d..91217a1d5d23 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ContentNegotiationConfigurer.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/ContentNegotiationConfigurer.java
@@ -131,7 +131,10 @@ public void strategies(@Nullable List strategies) {
* {@code "application/pdf"} regardless of the 'Accept' header.
* @deprecated as of 5.2.4. See class-level note in
* {@link ContentNegotiationManagerFactoryBean} on the deprecation of path
- * extension config options.
+ * extension config options. As there is no replacement for this method,
+ * for the time being it's necessary to continue using it in order to set it
+ * to {@code false}. In 5.3 when {@code false} becomes the default, use of
+ * this property will no longer be necessary.
*/
@Deprecated
public ContentNegotiationConfigurer favorPathExtension(boolean favorPathExtension) {
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/PathMatchConfigurer.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/PathMatchConfigurer.java
index 50d6716eb98a..0cb6889960c6 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/PathMatchConfigurer.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/PathMatchConfigurer.java
@@ -69,7 +69,9 @@ public class PathMatchConfigurer {
* @see #registeredSuffixPatternMatch
* @deprecated as of 5.2.4. See class-level note in
* {@link RequestMappingHandlerMapping} on the deprecation of path extension
- * config options.
+ * config options. As there is no replacement for this method, for the time
+ * being it's necessary to set it to {@code false}. In 5.3 when {@code false}
+ * becomes the default, use of this property will no longer be necessary.
*/
@Deprecated
public PathMatchConfigurer setUseSuffixPatternMatch(Boolean suffixPatternMatch) {
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestMappingHandlerMapping.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestMappingHandlerMapping.java
index 9b679e493818..2788eaa8e200 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestMappingHandlerMapping.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/RequestMappingHandlerMapping.java
@@ -58,7 +58,7 @@
* {@link RequestMapping @RequestMapping} annotations in
* {@link Controller @Controller} classes.
*
- * Note:
In 5.2.4,
+ * Deprecation Note:
In 5.2.4,
* {@link #setUseSuffixPatternMatch(boolean) useSuffixPatternMatch} and
* {@link #setUseRegisteredSuffixPatternMatch(boolean) useRegisteredSuffixPatternMatch}
* are deprecated in order to discourage use of path extensions for request
@@ -66,10 +66,6 @@
* {@link ContentNegotiationManager}). For further context, please read issue
* #24719.
*
- * In 5.3, {@link #setUseRegisteredSuffixPatternMatch(boolean) useRegisteredSuffixPatternMatch}
- * switches to being on by default so that path matching becomes constrained
- * to registered suffixes only.
- *
* @author Arjen Poutsma
* @author Rossen Stoyanchev
* @author Sam Brannen
@@ -101,7 +97,10 @@ public class RequestMappingHandlerMapping extends RequestMappingInfoHandlerMappi
*
Also see {@link #setUseRegisteredSuffixPatternMatch(boolean)} for
* more fine-grained control over specific suffixes to allow.
* @deprecated as of 5.2.4. See class level comment about deprecation of
- * path extension config options.
+ * path extension config options. As there is no replacement for this method,
+ * for the time being it's necessary to set it to {@code false}. In 5.3
+ * when {@code false} becomes the default, use of this property will no
+ * longer be necessary.
*/
@Deprecated
public void setUseSuffixPatternMatch(boolean useSuffixPatternMatch) {
@@ -115,8 +114,7 @@ public void setUseSuffixPatternMatch(boolean useSuffixPatternMatch) {
* when a "." appears in the path for other reasons.
*
By default this is set to "false".
* @deprecated as of 5.2.4. See class level comment about deprecation of
- * path extension config options note also that in 5.3 the default for this
- * property will switch from {@code false} to {@code true}.
+ * path extension config options.
*/
@Deprecated
public void setUseRegisteredSuffixPatternMatch(boolean useRegisteredSuffixPatternMatch) {