Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

path: Join documentation is misleading regarding Cleaned #29875

Closed
rillig opened this issue Jan 22, 2019 · 9 comments
Closed

path: Join documentation is misleading regarding Cleaned #29875

rillig opened this issue Jan 22, 2019 · 9 comments
Labels
Documentation FrozenDueToAge help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@rillig
Copy link
Contributor

rillig commented Jan 22, 2019

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
Copy link
Contributor

robpike commented Jan 22, 2019

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

@FiloSottile FiloSottile added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jan 23, 2019
@FiloSottile FiloSottile added this to the Go1.13 milestone Jan 23, 2019
@Avni-Sharma
Copy link

Has this been updated yet?

@rillig
Copy link
Contributor Author

rillig commented Mar 5, 2019

Has this been updated yet?

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

@agnivade
Copy link
Contributor

agnivade commented Jul 7, 2019

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.

@andybons andybons modified the milestones: Go1.13, Go1.14 Jul 8, 2019
@agnivade
Copy link
Contributor

agnivade commented Aug 6, 2019

@shivi28 - would you like to work on this ?

@erutherford
Copy link
Contributor

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

@agnivade
Copy link
Contributor

agnivade commented Sep 7, 2019

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

@gopherbot
Copy link

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

@pam4
Copy link

pam4 commented Nov 15, 2019

@erutherford, thanks for the fix; could you also fix filepath.Join documentation which has the same problem?

I noticed you removed "all empty strings are ignored", is that ok?
Without that sentence how can I be sure that the result of path.Join("", "foo") is "foo" and not "/foo"?

EDIT: I'm opening a new issue

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

9 participants