path/filepath: Join documentation inconsistencies with path.Join

[pam4]

This is a follow-up to #29875, which is closed.

Problems:

1. The fix was only applied to path.Join docs, but filepath.Join has the same problem and should be fixed too.
2. The new wording drops the sentence "all empty strings are ignored", leaving no clue that path.Join("", "foo") results in "foo" rather than "/foo".

New:

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.

Old:

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.

I think it should be clear that Join can return the empty string, but it should be also clear that empty strings at the beginning don't make the path absolute.

While I'm at it, I'm also confused by path.Dir:

Dir returns all but the last element of path, typically the path's directory. After dropping the final element using Split, the path is Cleaned and trailing slashes are removed. If the path is empty, Dir returns ".". If the path consists entirely of slashes followed by non-slash bytes, Dir returns a single slash. In any other case, the returned path does not end in a slash.

It should probably read "If the path consists entirely of slashes possibly followed by non-slash bytes" or "If the path consists entirely of slashes followed by zero or more non-slash bytes", otherwise the last sentence ("In any other case ...") is false.

[toothrot]

/cc @erutherford who worked on the updated documentation and @robpike, who owns path.

[erutherford]

Sorry, I meant to respond to this over the weekend, but ended up being sick instead :)

I think it should be clear that Join can return the empty string, but it should be also clear that empty strings at the beginning don't make the path absolute.

You're right this could have been clearer. Any leading empty strings are ignored in path.Join. I can take a look at updating this later today and look at updating filepath.Join as well.

While I'm at it, I'm also confused by path.Dir:

I can take a look at updating this too.

[gopherbot]

Change https://golang.org/cl/207797 mentions this issue: path: minor changes to improve documentation for Join

[pam4]

@erutherford, thanks! No hurry, I'm never sure if people see my replies on closed issues...

[erutherford]

Ok @toothrot and @pam4, I've got a CL up for the path.Join and filepath.Join changes.

[pam4]

@erutherford, "are" repetition typo in "Any leading empty elements are are ignored".

Your wording SGTM, but consider even just "Empty elements are ignored", since non leading ones don't make any difference after Clean.

[erutherford]

@pam4 thanks for catching that, I've corrected the error and adopted your suggestion.