doc: add note about path.basename on Windows

tniessen · addaleax · commit 3954b8f12d2b · 2020-09-22T23:48:14.000+02:00
PR-URL: #35065 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Gerhard Stöbich <deb2001-github@yahoo.de> Reviewed-By: Rich Trott <rtrott@gmail.com>
diff --git a/doc/api/path.md b/doc/api/path.md
@@ -87,6 +87,19 @@ path.basename('/foo/bar/baz/asdf/quux.html', '.html');
 // Returns: 'quux'
 ```
 
+Although Windows usually treats file names, including file extensions, in a
+case-insensitive manner, this function does not. For example, `C:\\foo.html` and
+`C:\\foo.HTML` refer to the same file, but `basename` treats the extension as a
+case-sensitive string:
+
+```js
+path.win32.basename('C:\\foo.html', '.html');
+// Returns: 'foo'
+
+path.win32.basename('C:\\foo.HTML', '.html');
+// Returns: 'foo.HTML'
+```
+
 A [`TypeError`][] is thrown if `path` is not a string or if `ext` is given
 and is not a string.
 
