path: Join documentation is misleading regarding Cleaned

[rillig]

As of Go 1.11.4, the documentation of path.Join says:

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.

Since Cleaned is written in uppercase, this suggests that path.Clean is called on the preliminary result of Join. For most cases this is true, but for the case of only empty filenames, it isn't. There, path.Join("") returns an empty string while path.Clean("") returns dot.

See https://play.golang.org/p/rjq7up_HplU.

[robpike]

A bug in the code, but maybe too hard to fix. Might need a documentation fix instead.

[Avni-Sharma]

Has this been updated yet?

[rillig]

Has this been updated yet?

No, otherwise the Gerrit change request would be linked with this issue.

[agnivade]

There is actually a test case for path.Join which joins two empty strings and checks the output is an empty string. So not sure if it is a bug.

For most cases this is true, but for the case of only empty filenames, it isn't. There, path.Join("") returns an empty string while path.Clean("") returns dot.

That is because path.Clean is called only for non-empty strings. Which is what the documentation tries to say. But I agree this part ; in particular, all empty strings are ignored. is not clear that Clean is being called after ignoring all empty strings. I believe updating the docs is the safest recourse.

[agnivade]

@shivi28 - would you like to work on this ?

[erutherford]

@agnivade I can work on this unless @shivi28 already has or was planning to.

[agnivade]

There hasn't been a response, so feel free to take it up.

[gopherbot]

Change https://golang.org/cl/194339 mentions this issue: path: inprove documentation to call out cases where Clean is called