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

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

Open
apiarian opened this Issue Sep 19, 2017 · 10 comments

Comments

Projects
None yet
6 participants
@apiarian

apiarian commented Sep 19, 2017

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?

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.

@gopherbot gopherbot added this to the Unreleased milestone Sep 19, 2017

@apiarian

This comment has been minimized.

apiarian commented Sep 19, 2017

Maybe with a -include-vendor flag?

@apiarian

This comment has been minimized.

apiarian commented Sep 19, 2017

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 apiarian closed this Sep 19, 2017

@apiarian

This comment has been minimized.

apiarian commented Sep 22, 2017

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

@apiarian apiarian reopened this Sep 22, 2017

@DanielHeath

This comment has been minimized.

DanielHeath commented Feb 21, 2018

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

This comment has been minimized.

apiarian commented Mar 28, 2018

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

@agnivade agnivade changed the title from x/tools/godoc should respect local vendor directory to x/tools/cmd/godoc: respect local vendor directory May 30, 2018

@agnivade

This comment has been minimized.

Member

agnivade commented May 30, 2018

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

This comment has been minimized.

apiarian commented May 30, 2018

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

This comment has been minimized.

DanielHeath commented May 30, 2018

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

This comment has been minimized.

Contributor

rsc commented Jun 11, 2018

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

@cpatulea

This comment has been minimized.

Contributor

cpatulea commented Jul 16, 2018

I agree, I've got a local 'go get' of https://github.com/prometheus/prometheus/, looking to read through the codebase to learn it. (go1.10.3) 'godoc -http=:6060' shows the top-level packages, but no mention of 'vendor'. One of the most important components of this project (tsdb) in under vendor.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment