cmd/doc: support -mod=readonly and other build flags

[gertcuykens]

Currently the other godoc html tool need significant changes before module support is ready. Also gopls has a long way to go to be a reliable tool for inspecting modules documentation which leave us with go doc to be the only tool we have for inspect modules.

GO111MODULE="on" (force to always enable modules)
% go doc github.com/gertcuykens/module/v5
doc: cannot find module providing package github.com/gertcuykens/module/v5: working directory is not part of a module
% mkdir test
% cd test
% go mod init test
go: creating new go.mod: module test
% go doc github.com/gertcuykens/module/v5
package module // import "github.com/gertcuykens/module/v5"
type CakeBaker struct{}
% cat go.mod 
module test
go 1.14
require github.com/gertcuykens/module/v5 v5.0.0 // indirect

What needs to be done for go doc specifically so that we have at least one reliable tool is:

A) go doc should never update go.mod files which it does and also does if cd is in GOPATH (related to #35070)

B) go doc should not require any go.mod file to be present in current working directory to inspect any existing module espacialy when GO111MODULE is always set to on

[stamblerre]

Coincidentally, @rentziass just sent out CL 203609 today, which adds support for a gopls symbols command. It would be fairly trivial to add a gopls doc which works per-package and also shows documentation in the style of go doc.

[gertcuykens]

Ok thx going to test this as soon as possible to figure out if gopls can be used as a replacement of go doc in a short amount of time :) #32875

[gertcuykens]

Please correct me if am wrong but https://go-review.googlesource.com/c/tools/+/203609/1/internal/lsp/cmd/symbols.go doesn't support modules, only input files located on your disk, so to be able to do what go doc does by first downloading the module and then look up a specific symbol or give a overview of all symbols of that specific module requires a lot more work I guess.

[jayconrod]

A) go doc should never update go.mod files which it does and also does if cd is in GOPATH (related to #35070)

This part is working as intended. go doc is part of the go command. Every subcommand related to modules will modify go.mod if it needs to look up a module (or fail if -mod=readonly) is set. go doc should not have significant differences from other commands.

B) go doc should not require any go.mod file to be present in current working directory to inspect any existing module espacialy when GO111MODULE is always set to on

This part is covered by #33710.

Also related: #32027.

cc @bcmills

[gertcuykens]

This part is working as intended. go doc is part of the go command. Every subcommand related to modules will modify go.mod if it needs to look up a module (or fail if -mod=readonly) is set. go doc should not have significant differences from other commands.

Ok kind of agree, but you don't have the mod readonly flag in go doc?

% go doc -mod=readonly github.com/gertcuykens/module/v5
flag provided but not defined: -mod

Anyway you are right this is more like a duplicate of #33710

[jayconrod]

Ok kind of agree, but you don't have the mod readonly flag in go doc?

That's true, we should probably add that and most of the other relevant build flags. I'll reopen this issue for that.

[agnivade]

Now that GOFLAGS is there, it is a simple way to pass flags across binaries. And go doc already supports the -mod flag through GOFLAGS and others too, like -x. Are we sure we want to add explicit command line flags to all go subcommands such as these ?

[gertcuykens]

GOFLAGS will do but I am pretty sure 99% of the community has no idea what the general GOFLAGS variables are. And if we go for GOFLAGS only, which is fine by me and maybe even preferable because it prevents flag clutter, then it should be made consistent with other commands by removing for example -mod from all other go commands.

[esprehn]

We were bit by this recently. godoc will mutate the go.sum unless told otherwise, which means when run locally things appear to work fine, but if run remotely on a readonly filesystem they fail. It looks like the other go commands now run in readonly mode by default, should godoc do that as well? It's surprising it'll fix up things automatically.

[bcmills]

@esprehn, now that -mod=readonly is the default I think it's worth filling a separate issue for the mutations you observed (along with clear steps to reproduce them).

I'd like to keep this issue focused on flag support (for example, using -mod=readonly vs. -mod=vendor when a vendor subdirectory is present).