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

Jump to bottom

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

Closed
dmitshur opened this issue Jun 26, 2016 · 6 comments
Closed

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

dmitshur opened this issue Jun 26, 2016 · 6 comments
Labels
FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Unreleased

Comments

@dmitshur
Copy link
Contributor

dmitshur commented Jun 26, 2016 •
edited

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).
@quentinmit quentinmit modified the milestones: Go1.8, Unreleased Jul 29, 2016
@dmitshur
Copy link
Contributor Author

dmitshur commented Mar 10, 2018 •
edited

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.

@andybons andybons added help wanted NeedsFix The path to resolution is known, but the work has not been done. labels Mar 11, 2018
@agnivade
Copy link
Contributor

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

dmitshur commented Apr 24, 2018 •
edited

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)
}

@dmitshur dmitshur changed the title x/tools/cmd/godoc: Does not respect relative import paths that match standard commands. cmd/doc, x/tools/cmd/godoc: do not respect relative import paths that match standard commands Apr 24, 2018
@agnivade
Copy link
Contributor

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 agnivade mentioned this issue May 17, 2018
Closed
@agnivade agnivade changed the title cmd/doc, x/tools/cmd/godoc: do not respect relative import paths that match standard commands cmd/doc: do not respect relative import paths that match standard commands Oct 11, 2018
@agnivade
Copy link
Contributor

Removing godoc, now that CLI support is gone.

@agnivade
Copy link
Contributor

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

@golang golang locked and limited conversation to collaborators Mar 25, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Unreleased
Development

No branches or pull requests
5 participants
@quentinmit @andybons @agnivade @dmitshur @gopherbot