Clarification on path extension deprecations

Closes gh-24642

Author: rstoyanchev

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)}.
  *
- * <p><strong>Note:</strong> As of 5.2.4,
+ * <p><strong>Deprecation Note:</strong> 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
  * <a href="https://github.com/spring-projects/spring-framework/issues/24179">#24719</a>.
- *
  * @author Rossen Stoyanchev
  * @author Brian Clozel
  * @since 3.2
@@ -149,7 +148,10 @@ public void setStrategies(@Nullable List<ContentNegotiationStrategy> 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) {

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

@@ -131,7 +131,10 @@ public void strategies(@Nullable List<ContentNegotiationStrategy> 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) {

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) {

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

@@ -58,18 +58,14 @@
  * {@link RequestMapping @RequestMapping} annotations in
  * {@link Controller @Controller} classes.
  *
- * <p><strong>Note:</strong></p> In 5.2.4,
+ * <p><strong>Deprecation Note:</strong></p> 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
  * mapping and for content negotiation (with similar deprecations in
  * {@link ContentNegotiationManager}). For further context, please read issue
  * <a href="https://github.com/spring-projects/spring-framework/issues/24179">#24719</a>.
  *
- * <p>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
 	 * <p>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.
 	 * <p>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) {