cmd/doc: do not respect relative import paths that match standard commands

[dmitshur]

Both the doc (typically invoked via go doc) and godoc commands are affected.

(Edit: This no longer applies to x/tools/cmd/godoc because it's CLI support is removed in #25443.)

go doc and godoc commands will always print docs for cmd/go command even if you provide a relative import path like ./cmd/go that may resolve to another Go package (or no package).

go list ./cmd/go works as expected.

This affects go doc ./cmd/gofmt and other similar queries too.

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

   $ go version
   go version go1.6.2 darwin/amd64

2. 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/GoWorkspace1:/Users/Dmitri/GoWorkspace2"
   GORACE=""
   GOROOT="/usr/local/go"
   GOTOOLDIR="/usr/local/go/pkg/tool/darwin_amd64"
   GO15VENDOREXPERIMENT="1"
   CC="clang"
   GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fno-common"
   CXX="clang++"
   CGO_ENABLED="1"

3. What did you do?

   $ cd $GOPATH/src/foo/bar
   $ go doc ./cmd/notexist
   $ go doc ./cmd/go
   

4. What did you expect to see?

   $ go doc ./cmd/notexist
   doc: no such package ./cmd/notexist
   exit status 1
   
   $ go doc ./cmd/go
   doc: no such package ./cmd/go
   exit status 1
   

   Or documentation for the actual package resolved by go list ./cmd/go, if it exists.

5. What did you see instead?

   $ go doc ./cmd/notexist
   doc: no such package ./cmd/notexist
   exit status 1
   
   $ go doc ./cmd/go
   COMMAND DOCUMENTATION
   
       Go is a tool for managing Go source code.
   
       Usage:
   
   	go command [arguments]
   
       The commands are:
   

   Documentation for cmd/go showed up, as if I had typed go doc cmd/go (note without the relative path).

[dmitshur]

I don't know if this information is relevant here or not, but I'll share it in case it is. go help list notes that:

Import paths beginning with "cmd/" only match source code in the Go repository.

That may or may not be related to this bug.

Note that this doesn't validate the behavior. It's still a bug in the go doc command, since the issue is about "./cmd/go" which does not start with "cmd/" (because of the "./" prefix). go list isn't affected.

[agnivade]

Quick question - You mention the godoc command at the start of the issue. But later, you mention go doc ./cmd/go.

It's interesting because if I do go doc ./cmd/go, I can see the issue. But if I do gotip doc ./cmd/go, I don't. (gotip is an alias to the go tip binary).

Whereas, if I do ./godoc ./cmd/go I see the issue again. Pardon my ignorance, but how is go doc different from godoc ? Trying to read the code, I can see that go doc shells out to a binary but I couldn't find what. Or I might be mistaken.

On a different note - the godoc command line package search code is very hairy. As is relevant from the CLs trying to solve this issue #14447. I plan to take a look at the bugs affecting godoc command line, but first I would like to have a better understanding of things.

[dmitshur]

Sorry, I've edited my original issue to make it more clear and specific.

how is go doc different from godoc?

They are two different commands:

• go doc executes doc binary, its source is at cmd/doc, and it typically lives in GOROOT/pkg/tool/{{GOOS}}_{{GOARCH}}/doc.
• godoc binary source code is at golang.org/x/tools/cmd/godoc, and it typically lives in GOROOT/bin/godoc.

Trying to read the code, I can see that go doc shells out to a binary but I couldn't find what.

Check your GOROOT/pkg/tool/{{GOOS}}_{{GOARCH}} directory, it should be there as doc.

If you want to see more details, expand the compressed section below.

More Details

For each release of Go (e.g., 1.9, 1.9.1, 1.10, etc.), a version of the golang.org/x/tools/cmd/godoc binary is built (I think the source code for that is here) and copied to the GOROOT/bin directory of the release.

When you use godoc, assuming your GOROOT/bin directory is early in PATH, that is the binary executed. However, if you installed golang.org/x/tools/cmd/godoc yourself or built Go from source, you might run your own different version of godoc instead. Do which godoc to find out.

When you use go doc, it's the doc subcommand of the cmd/go command (similar to go build, go install, etc.). The doc subcommand simply invokes doc binary directly from the tool (e.g., GOROOT/pkg/tool/darwin_amd64) directory:

go/src/cmd/go/internal/doc/doc.go

Lines 121 to 123 in cd037bc

	func runDoc(cmd *base.Command, args []string) {
	base.Run(cfg.BuildToolexec, base.Tool("doc"), args)
	}

[agnivade]

Thanks. Yes, I was looking at base.Run(cfg.BuildToolexec, base.Tool("doc"), args), but couldn't figure out where the "doc" was coming from. I was looking at cmd/go/internal/doc instead of cmd/doc.

So it looks like the fix needs to be applied to 2 separate repos. It's interesting that the same bug got manifested in 2 different repos.

[agnivade]

Removing godoc, now that CLI support is gone.

[agnivade]

This seems to be fixed now from 1.11 onwards. Closing.