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>

1 files changed, 4 insertions, 3 deletions

diff --git a/src/path/path.go b/src/path/path.go
index 5c905110a1..09a9d00c34 100644
--- 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 != "" {