path: improve documentation to call out cases where Clean is called

Rewording the comments for Join to do a better job of calling out
when Clean is called. Also clarifing other portions of the comment.

Fixes #29875

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

diff --git a/src/path/path.go b/src/path/path.go
index 5c905110a1bd72a4d34e49654d3583c19be5eaf8..09a9d00c34b7767aa9fd299d5a68c5997c5523fe 100644 (file)
--- a/src/path/path.go
+++ b/src/path/path.go
@@ -149,9 +149,10 @@ 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
-// separating slash if necessary. The result is Cleaned; in particular,
-// all empty strings are ignored.
+// 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.
 func Join(elem ...string) string {
        for i, e := range elem {
                if e != "" {