path/filepath: document that Clean does not change Windows volume names

Fixes #58348

Change-Id: I4aac0285f11618a45aca6b13c2da2a10a803a9b5
Reviewed-on: https://go-review.googlesource.com/c/go/+/469955
Reviewed-by: Bryan Mills <bcmills@google.com>
Auto-Submit: Damien Neil <dneil@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Damien Neil <dneil@google.com>

diff --git a/src/path/filepath/path.go b/src/path/filepath/path.go
index 32dd887998650bff7cff4456c1ea1e023fcaa522..520020811715153428c6c3ec74303e53cdfe9ff0 100644 (file)
--- a/src/path/filepath/path.go
+++ b/src/path/filepath/path.go
@@ -84,6 +84,10 @@ const (
 // If the result of this process is an empty string, Clean
 // returns the string ".".
 //
+// On Windows, Clean does not modify the volume name other than to replace
+// occurrences of "/" with `\`.
+// For example, Clean("//host/share/../x") returns `\\host\share\x`.
+//
 // See also Rob Pike, “Lexical File Names in Plan 9 or
 // Getting Dot-Dot Right,”
 // https://9p.io/sys/doc/lexnames.html