From 8452ba800cd038390f0fce45dde9ad8a271a7ce6 Mon Sep 17 00:00:00 2001
From: Mark Thomas <markt@apache.org>
Date: Wed, 22 Jan 2025 12:11:33 +0000
Subject: [PATCH] Update docs

---
 .../apache/tomcat/util/http/RequestUtil.java   | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/java/org/apache/tomcat/util/http/RequestUtil.java b/java/org/apache/tomcat/util/http/RequestUtil.java
index 1c1ed0de13e2..fe4d1e639a46 100644
--- a/java/org/apache/tomcat/util/http/RequestUtil.java
+++ b/java/org/apache/tomcat/util/http/RequestUtil.java
@@ -30,13 +30,13 @@ private RequestUtil() {
 
 
     /**
-     * Normalize a relative URI path that may have relative values ("/./", "/../", and so on ) it it.
-     * <strong>WARNING</strong> - This method is useful only for normalizing application-generated paths. It does not
-     * try to perform security checks for malicious input.
+     * Normalize a relative URI path. This method normalizes "/./", "/../", "//" and "\". If the input path is an
+     * attempt to 'escape the root' (e.g. /../input.txt) then {@code null} is returned to prevent attempts to 'escape
+     * the root'. <strong>WARNING</strong> - No other URI validation checks are performed.
      *
      * @param path Relative path to be normalized
      *
-     * @return The normalized path or <code>null</code> if the path cannot be normalized
+     * @return The normalized path or {@code null} if the input path attempts to 'escape the root'.
      */
     public static String normalize(String path) {
         return normalize(path, true);
@@ -44,14 +44,14 @@ public static String normalize(String path) {
 
 
     /**
-     * Normalize a relative URI path that may have relative values ("/./", "/../", and so on ) it it.
-     * <strong>WARNING</strong> - This method is useful only for normalizing application-generated paths. It does not
-     * try to perform security checks for malicious input.
+     * Normalize a relative URI path. This method normalizes "/./", "/../" and "//". This method optionally normalizes
+     * "\". If the input path is an attempt to 'escape the root' (e.g. /../input.txt) then {@code null} is returned to
+     * prevent attempts to 'escape the root'. <strong>WARNING</strong> - No other URI validation checks are performed.
      *
      * @param path             Relative path to be normalized
-     * @param replaceBackSlash Should '\\' be replaced with '/'
+     * @param replaceBackSlash Should '\\' be normalized to '/'
      *
-     * @return The normalized path or <code>null</code> if the path cannot be normalized
+     * @return The normalized path or {@code null} if the input path attempts to 'escape the root'.
      */
     public static String normalize(String path, boolean replaceBackSlash) {