path: minor changes to improve documentation for Join

Reworking the comments in path to call out how leading
empty elements are treated. Also updating filepath.Join
since it shared much of the wording from path.Join.

Updates #35655

Change-Id: I5b15c5d36e9d19831ed39e6bcc7f2fd6c1330033
Reviewed-on: https://go-review.googlesource.com/c/go/+/207797
Reviewed-by: Rob Pike <r@golang.org>

diff --git a/src/path/filepath/path.go b/src/path/filepath/path.go
index aba1717e7d5e0c7186a0e2a91adb011730d71f0e..26f183318923d899d372812775c349ed57e9e650 100644 (file)
--- a/src/path/filepath/path.go
+++ b/src/path/filepath/path.go
@@ -201,11 +201,13 @@ func Split(path string) (dir, file string) {
        return path[:i+1], path[i+1:]
 }
 
-// Join joins any number of path elements into a single path, adding
-// a Separator if necessary. Join calls Clean on the result; in particular,
-// all empty strings are ignored.
-// On Windows, the result is a UNC path if and only if the first path
-// element is a UNC path.
+// Join joins any number of path elements into a single path,
+// separating them with an OS specific Separator. Empty elements
+// are ignored. The result is Cleaned. However, if the argument
+// list is empty or all its elements are empty, Join returns
+// an empty string.
+// On Windows, the result will only be a UNC path if the first
+// non-empty element is a UNC path.
 func Join(elem ...string) string {
        return join(elem)
 }

diff --git a/src/path/path.go b/src/path/path.go
index 09a9d00c34b7767aa9fd299d5a68c5997c5523fe..c513114b4d7df3c692a286382e0ac54f0868a484 100644 (file)
--- a/src/path/path.go
+++ b/src/path/path.go
@@ -149,10 +149,11 @@ func Split(path string) (dir, file string) {
        return path[:i+1], path[i+1:]
 }
 
-// Join joins the argument's path elements into a single path,
-// separating them with slashes. The result is Cleaned. However,
-// if the argument list is empty or all its elements are empty,
-// Join returns an empty string.
+// Join joins any number of path elements into a single path,
+// separating them with slashes. Empty elements are ignored.
+// The result is Cleaned. However, if the argument list is
+// empty or all its elements are empty, Join returns
+// an empty string.
 func Join(elem ...string) string {
        for i, e := range elem {
                if e != "" {