doc: improve path.posix.normalize docs

sjlehn · MylesBorins · commit 28add410c2ce · 2017-07-11T17:43:47.000+01:00
Add section to path docs that explains that path.posix.normalize does not replace Windows slashes with POSIX slashes because POSIX does not recognize / as a valid path separator. Fixes: #12298 PR-URL: #12700 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: David Cai <davidcai1993@yahoo.com>
diff --git a/doc/api/path.md b/doc/api/path.md
@@ -306,8 +306,9 @@ The `path.normalize()` method normalizes the given `path`, resolving `'..'` and
 `'.'` segments.
 
 When multiple, sequential path segment separation characters are found (e.g.
-`/` on POSIX and `\` on Windows), they are replaced by a single instance of the
-platform specific path segment separator. Trailing separators are preserved.
+`/` on POSIX and either `\` or `/` on Windows), they are replaced by a single
+instance of the platform specific path segment separator (`/` on POSIX and
+`\` on Windows). Trailing separators are preserved.
 
 If the `path` is a zero-length string, `'.'` is returned, representing the
 current working directory.
@@ -326,6 +327,14 @@ path.normalize('C:\\temp\\\\foo\\bar\\..\\');
 // Returns: 'C:\\temp\\foo\\'
 ```
 
+Since Windows recognizes multiple path separators, both separators will be
+replaced by instances of the Windows preferred separator (`\`):
+
+```js
+path.win32.normalize('C:////temp\\\\/\\/\\/foo/bar');
+// Returns: 'C:\\temp\\foo\\bar'
+```
+
 A [`TypeError`][] is thrown if `path` is not a string.
 
 ## path.parse(path)
