path/filepath: document that filepath.Join("c:", "a") returns `c:\a` not `c:a` on Windows

[alexbrainman]

This program:

package main

import (
    "fmt"
    "path/filepath"
)

func main() {
    fmt.Println(filepath.Join("a"))
    fmt.Println(filepath.Join("c:", "a"))
}

displays:

C:\dev\src\foo>go run main.go
a
c:\a

C:\dev\src\foo>

but should display:

C:\dev\src\foo>go run main.go
a
c:a

C:\dev\src\foo>

or

C:\dev\src\foo>go run main.go
a
c:.\a

C:\dev\src\foo>

Alex

[jhoonb]

No...
the doc says:
"The returned path ends in a slash only if it represents a root directory, such as "/" on Unix or C:\ on Windows."
http://golang.org/pkg/path/filepath/#Clean

See code:
http://golang.org/src/path/filepath/path.go?s=2213:2243#L71

[akavel]

Related discussion with more details: https://groups.google.com/forum/#!topic/golang-nuts/xFWpetTOPp4

[alexbrainman]

@xiofen I am no good at writing documentation. So, if you feel strongly about it, suggest you own change - http://golang.org/doc/contribute.html

Thank you.

Alex

[jhoonb]

I agree

[nerdatmath]

Perhaps "adding a separator if one is not already present"

[alexbrainman]

@minux and me disagree about https://go-review.googlesource.com/#/c/11882 change. We need more reviewers to lean us one way or the other. Please help. Thank you.

Alex

[Thomasdezeeuw]

Although I do think the new behaviour is better, I also think this is a breaking change. So this should be a no-go for Go1.x.

[ianlancetaylor]

I don't see a clear justification for the change in CL 11882. I see the logic in it, but the function was never documented to work that way, and it could clearly break existing programs. I think we should document the current behavior, as this issue suggests.

[nerdatmath]

Intuitively, I see filepath.Join as giving the path you would get if you did a Chdir to each path in sequence (without looking at the filesystem, so you could end up with a relative path). On Windows if I Chdir("c:") and then Chdir("abc") I end up in the same place as if I did Chdir("c:abc"). This is different from Chdir("c:\abc") because on Windows you have a working directory for each drive letter.

I don't have any valid intuition about the current behavior. It strikes me as just a symbol manipulation that makes Unix-specific assumptions even though filepath is supposed to be a cross platform module.

Although it could break existing code, I suspect any such existing code is already buggy, and this change would make it less buggy.