Skip to content

x/tools/cmd/godoc: godoc suggests using arguments it doesn't understand when confused by vendoring #45126

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.

Sign up for GitHub

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
Closed
lpar opened this issue Mar 19, 2021 · 12 comments
Closed

x/tools/cmd/godoc: godoc suggests using arguments it doesn't understand when confused by vendoring #45126

lpar opened this issue Mar 19, 2021 · 12 comments
Assignees
@agnivade
Labels
NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone
Unreleased

Comments

@lpar
Copy link

lpar commented Mar 19, 2021

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

$ go version
go version go1.16.2 linux/amd64

Does this issue reproduce with the latest release?

Yes

What did you do?

godoc -http=localhost:6060
using module mode; GOMOD=/home/meta/go/src/github.com/cbroglie/mustache/go.mod
failed to determine if vendoring is enabled: err: exit status 1: stderr: go: inconsistent vendoring in /home/meta/go/src/github.com/cbroglie/mustache:
	github.com/yuin/goldmark@v1.3.2: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt
	golang.org/x/mod@v0.4.2: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt
	golang.org/x/net@v0.0.0-20210316092652-d523dce5a7f4: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt
	golang.org/x/sync@v0.0.0-20210220032951-036812b2e83c: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt
	golang.org/x/sys@v0.0.0-20210319071255-635bc2c9138d: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt
	golang.org/x/tools@v0.1.0: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt

	To ignore the vendor directory, use -mod=readonly or -mod=mod.
	To sync the vendor directory, run:
		go mod vendor

However:

% godoc -http=localhost:6060 -mod=mod
flag provided but not defined: -mod
usage: godoc -http=localhost:6060
[ rest of help text omitted ]
@cherrymui cherrymui changed the title The godoc command suggests using arguments it doesn't understand when confused by vendoring x/tools/cmd/godoc: godoc suggests using arguments it doesn't understand when confused by vendoring Mar 19, 2021
@cherrymui
Copy link
Member

Are you using golang.org/x/tools/cmd/godoc ? What version are you using? Thanks.

@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Mar 19, 2021
@gopherbot gopherbot added this to the Unreleased milestone Mar 19, 2021
@cherrymui cherrymui added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Mar 19, 2021
@cherrymui
Copy link
Member

cc @dmitshur

@lpar
Copy link
Author

lpar commented Mar 19, 2021

I'm using the version installed by running go get -u golang.org/x/tools/... a few minutes ago.

@agnivade
Copy link
Contributor

The -mod flag is for the underlying Go command, which you'll have to pass via the GOFLAGS env var. The error is coming from the underlying Go command, I agree this can be a bit confusing.

@dmitshur
Copy link
Contributor

dmitshur commented Mar 19, 2021 •
edited
Loading

As far as I can tell godoc is doing the right thing, it is reporting that it "failed to determine if vendoring is enabled" and provides stderr output from cmd/go to provide more context (without that context, it would be very hard to understand why it failed).

It goes poorly because the cmd/go stderr output includes advice that's meant to be helpful when a human runs cmd/go directly, but is misleading when another tool runs cmd/go.

Perhaps it makes sense to file a cmd/go feature request issue to see if there's a way to invoke cmd/go in a way that doesn't include its human-facing advice. Otherwise, godoc has to either not include the details (cmd/go's stderr) when saying that it failed to determine if vendoring is enabled, or try to do work itself to filter out advice that isn't directly applicable.

@jayconrod Any thoughts or preferences on this? Have there been requests from authors of other tools (that need to run cmd/go internally) to be able to omit its human-facing advice?

@jayconrod
Copy link
Contributor

#30134 is an issue for machine-readable error codes in cmd/go messages. I don't think it's likely to be fixed soon though.

Maybe godoc could make it clearer this output is coming from the go command, and specifically, what command was run? At least the advice to run go mod vendor is useful.

@lpar
Copy link
Author

lpar commented Mar 19, 2021

I also don't really understand why godoc needs to look at vendored dependencies. I mean, I'm not expecting to read the documentation for those, just for my project.

@dmitshur
Copy link
Contributor

godoc serves documentation for all packages in the build list, which includes packages in the main module as well as dependencies. It follows the logic of the go command and uses automatic vendoring (see #35429).

Hopefully the inconsistent vendoring problem is rare. If someone runs into it, it means the normal go command cannot build code either. Let me know if that's not the case.

Maybe godoc could make it clearer this output is coming from the go command, and specifically, what command was run?

This seems like a good solution. I don't see much else that can be done.

@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Mar 19, 2021
@agnivade agnivade self-assigned this Mar 20, 2021
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/303529 mentions this issue: cmd/godoc: annotate errors coming from the go command

@matttproud
Copy link
Contributor

matttproud commented Aug 24, 2021 •
edited
Loading

I can confirm this when running godoc on the standard Go distribution (e.g., to prototype and preview local changes to package documentation). In particular, even when using GOFLAGS for environmental passthrough, godoc only renders what appears to be a cached version of the standard distribution and not the local changes to package documentation.

@seankhliao
Copy link
Member

@matttproud that is unrelated and you should be using the -goroot flag

@seankhliao
Copy link
Member

cmd/godoc was deprecated.

@seankhliao seankhliao closed this as not planned Won't fix, can't repro, duplicate, stale Dec 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@agnivade agnivade

Labels
NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Milestone
Unreleased
Development

No branches or pull requests
8 participants
@matttproud @jayconrod @lpar @agnivade @dmitshur @gopherbot @seankhliao @cherrymui