x/tools/cmd/godoc: respect local vendor directory

[apiarian]

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

1.9

Does this issue reproduce with the latest release?

yes

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

GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/apasechnik/code/go"
GORACE=""
GOROOT="/usr/local/Cellar/go/1.9/libexec"
GOTOOLDIR="/usr/local/Cellar/go/1.9/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/3h/jgsxmkp14dj9tr4bk7x4vw9hf25z7p/T/go-build553012486=/tmp/go-build -gno-record-gcc-switches -fno-common"
CXX="clang++"
CGO_ENABLED="1"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"

What did you do?

• cd $PROJECT_DIRECTORY
• ran godoc -http=:6060
• looking at http://localhost:6060/pkg/

What did you expect to see?

Packages in the $PROJECT_DIRECTORY/vendor directory along with things in $GOPATH and $GOROOT`.

What did you see instead?

Only things in $GOPATH and $GOROOT.

[apiarian]

Maybe with a -include-vendor flag?

[apiarian]

Nope, seems like I was wrong. the vendored code does show up in search results and can be viewed, though it does show the wrong import path (includes the full /vendor structure instead of the plain package path). I just had to wait for the index to finish building.

[apiarian]

Nope, after some more research things aren't working quite as expected.

I've set up a few packages for testing: https://github.com/apiarian/vscode-go-test-docs-main https://github.com/apiarian/vscode-go-test-docs-gopathonly and https://github.com/apiarian/vscode-go-test-docs-vendoroverride

I see the following output:

$ pwd
/Users/apasechnik/code/go/src/github.com/apiarian/vscode-go-test-docs-main

$ godoc github.com/apiarian/vscode-go-test-docs-vendoroverride
use 'godoc cmd/github.com/apiarian/vscode-go-test-docs-vendoroverride' for documentation on the github.com/apiarian/vscode-go-test-docs-vendoroverride command

PACKAGE DOCUMENTATION

package vendoroverride
    import "github.com/apiarian/vscode-go-test-docs-vendoroverride"

    Package vendoroverride in the gopath defines foo and bar with some docs.
    These will be overridden in the vendor directory of the main package. We
    could probably do the same with branches or something, but this seems a
    bit more controllable.

FUNCTIONS

func Bar() string
    Bar returns the string "bar" (the gopath version)

func Foo() string
    Foo returns the string "foo" (the gopath version)

Which, is the $GOPATH version of that documentation, not the vendor/ version.

Granted, it is possible to do something like this (note the ./vendor/ prefix on the godoc argument.

$ godoc ./vendor/github.com/apiarian/vscode-go-test-docs-vendoroverride
PACKAGE DOCUMENTATION

package vendoroverride
    import "./vendor/github.com/apiarian/vscode-go-test-docs-vendoroverride"

    Package vendoroverride in the gopath defines foo and bar with some docs.
    These have been overridden in the vendor directory of the main package.
    We could probably do the same with branches or something, but this seems
    a bit more controllable.

FUNCTIONS

func Bar() string
    Bar returns the string "foo" (the vendor version)

func Foo() string
    Foo returns the string "bar" (the vendor version)

But that puts the burden on the tool which may want to use this godoc output (such as an editor) to either know that the package has a vendored version, or to try the vendor prefix first, then try without the prefix if the package couldn't be found.

So, I'm reopening this issue to enable local vendor support for the command line form of the godoc command. It wouldn't need to be enabled by default, but something like -include-vendor would be very useful for tools.

For a bit more context: I'm looking to get docs for a package within my text editor. godoc provides the best output for a full package's documentation of all the tools I've seen for this purpose. go doc only shows the signatures of exported elements, not their docs as well.

Related to zmb3/gogetdoc#29 and microsoft/vscode-go#1237

[DanielHeath]

Agreed.

I have recently moved from using an app-specific $GOPATH to using dep.

The only workflow change I haven't been able to adjust to is the loss of godoc.

When my app had its own $GOPATH, running godoc showed me the information on every package I was using (and none of the packages I had installed globally).

Now I'm using dep and vendor, it shows me every package I have installed globally (noise), and none of my actual dependencies (signal).

[apiarian]

In the meantime I wrote this wrapper: https://github.com/apiarian/godocv (plus adds /usr/bin/less pager pagination)

[agnivade]

Just to be clear, you want godoc to automatically recognize which directory it is being run from and show the documentation from a vendored package if it exists ?

Because if I see -
$godoc github.com/apiarian/vscode-go-test-docs-vendoroverride - it is clear to me that godoc should show documentation from the GOPATH. Personally, it is simpler to wrap my head around passing explicit vendor folder path rather than the tool do certain magic when you are in a particular folder. Passing a flag might still be okay, but I'm not sure if we want to add another flag to an already big list of flags.

/cc @andybons

[apiarian]

It doesn’t need to be automatic. You could certainly pass in a parameter like -context which can be any path and it will show you the documentation for the package which would be compiled against from that path, vendored or otherwise. In fact it probably shouldn’t be automatic for the official program since it would be a breaking change to the logic. I’ve made it automatic for my wrapper since that is explicitly a new command.

The idea is that you can request the godoc for the package by it’s import path and get the correct godoc whether the package is vendored or not.

[DanielHeath]

I'm open to alternatives; the use case is 'I want to see documentation for the version of libraries that will be built into the software I am working on.'

[rsc]

In general it seems like godoc is going to need to become version-aware (vgo-aware). Not entirely sure what that's going to look like. /cc @alandonovan