path/filepath: document Dir behavior for Windows volume-only paths

Clarify that on Windows, Dir("C:") returns "C:." (the current directory
on drive C) rather than a root path. This is because Clean("") returns
"." and Dir prepends the volume name.

Fixes #77314

Change-Id: Idbc8ef5a4905e8587268428503a98a28c8c2f6e9
Reviewed-on: https://go-review.googlesource.com/c/go/+/740902
Reviewed-by: Rob Pike <r@golang.org>
TryBot-Bypass: Dmitri Shuralyov <dmitshur@google.com>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Junyang Shao <shaojunyang@google.com>
Reviewed-by: Olivier Mengué <olivier.mengue@gmail.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>

1 files changed, 4 insertions, 0 deletions

diff --git a/src/path/filepath/path.go b/src/path/filepath/path.go
index ecf201ac00..cd0fcc9c34 100644
--- a/src/path/filepath/path.go
+++ b/src/path/filepath/path.go
@@ -463,6 +463,10 @@ func Base(path string) string {
 // If the path is empty, Dir returns ".".
 // If the path consists entirely of separators, Dir returns a single separator.
 // The returned path does not end in a separator unless it is the root directory.
+//
+// On Windows, given a volume-only name such as "C:", Dir returns "C:.",
+// the current directory on drive C. To obtain the drive's root "C:\",
+// use [VolumeName] combined with a separator.
 func Dir(path string) string {
 	return filepathlite.Dir(path)
 }