go/build: document that Context.HasSubdir does not check existence of dir

[dmitshur]

What version of Go are you using (go version)?

$ go version
go version go1.7.3 darwin/amd64

What operating system and processor architecture are you using (go env)?

$ go env
GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/Dmitri/Dropbox/Work/2013/GoLanding:/Users/Dmitri/Dropbox/Work/2013/GoLand"
GORACE=""
GOROOT="/usr/local/go"
GOTOOLDIR="/usr/local/go/pkg/tool/darwin_amd64"
CC="clang"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/tw/kgz4v2kn4n7d7ryg5k_z3dk40000gn/T/go-build353413060=/tmp/go-build -gno-record-gcc-switches -fno-common"
CXX="clang++"
CGO_ENABLED="1"

What did you do?

I read the documentation for Context.HasSubdir:

https://godoc.org/go/build#Context.HasSubdir

// HasSubdir reports whether dir is a subdirectory of
// (perhaps multiple levels below) root.
// If so, HasSubdir sets rel to a slash-separated path that
// can be joined to root to produce a path equivalent to dir.
// If HasSubdir is nil, Import uses an implementation built on
// filepath.EvalSymlinks.
HasSubdir func(root, dir string) (rel string, ok bool)

What did you expect to see?

Based on the name of the func and the phrase "whether dir is a subdirectory of root", I expected the default implementation (when HasSubdir is nil), which uses filepath.EvalSymlinks, to return false if the directory doesn't exist.

I also asked another person, and that was their understanding of the expected behavior too.

What did you see instead?

After looking into the implementation, I learned that the default implementation (and therefore, all custom implementation that are expected to act in the same way) does not try to ensure that dir is a subdirectory of root.

Instead, it simply reports "whether dir is a path that points to what would be a subdirectory (possibly multiple levels below) of root".

In other words, it does not check that dir is a directory that actually exists. It simply does a lexical path check (also uses filepath.EvalSymlinks to resolve potential symlinks).

---

This is one of those situations where I'm not completely sure if this is a bug in the implementation, or a case of slightly poor/misleading documentation. Looking more into the history of the relevant code, and the fact that IsDir exists solely to check existence of a directory, I am 80%+ confident the current behavior is correct and this is just a documentation issue.

Update: After spending more time with the code, I am now 97%+ confident the current behavior is correct, and this is just a documentation/naming issue. IsDir exists for checking if a directory exists, so it's not the responsibility of HasSubdir to check that too.

What do other people think about the current phrasing?

I think perhaps it should be clarified that dir does not need to exist for HasSubdir to return true.

Maybe it can be clarified by rewriting it to be something like this (except better)?

// HasSubdir reports whether dir is a path that points to
// what would be a subdirectory of (perhaps multiple levels below) root
// (but it does not try to check that dir currently exists).
// If so, HasSubdir sets rel to a slash-separated path that
// can be joined to root to produce a path equivalent to dir.
// If HasSubdir is nil, Import uses an implementation built on
// filepath.EvalSymlinks.
HasSubdir func(root, dir string) (rel string, ok bool)

[gopherbot]

CL https://golang.org/cl/33158 mentions this issue.

[gopherbot]

CL https://golang.org/cl/34240 mentions this issue.