doc: note that path.normalize deviates from POSIX

tniessen · targos · commit 177e13cb0dce · 2024-02-15T12:05:53.000+01:00
PR-URL: #51513 Refs: #51345 Reviewed-By: Yagiz Nizipli <yagiz.nizipli@sentry.io> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
diff --git a/doc/api/path.md b/doc/api/path.md
@@ -361,6 +361,14 @@ instance of the platform-specific path segment separator (`/` on POSIX and
 If the `path` is a zero-length string, `'.'` is returned, representing the
 current working directory.
 
+On POSIX, the types of normalization applied by this function do not strictly
+adhere to the POSIX specification. For example, this function will replace two
+leading forward slashes with a single slash as if it was a regular absolute
+path, whereas a few POSIX systems assign special meaning to paths beginning with
+exactly two forward slashes. Similarly, other substitutions performed by this
+function, such as removing `..` segments, may change how the underlying system
+resolves the path.
+
 For example, on POSIX:
 
 ```js
