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>

1 files changed, 7 insertions, 5 deletions

diff --git a/src/path/filepath/path.go b/src/path/filepath/path.go
index aba1717e7d..26f1833189 100644
--- 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)
 }