proposal: cmd/go: allow versioned go doc commands

[dolmen]

Proposal Details

Add support for go doc <pkg>@<version> ... to allow to display godoc from a package in a module independently of the local Go context (go.mod). Like go install and go run.

New usage (adapted from go help doc):

	go doc <pkg>[@<version>]
	go doc <sym>[.<methodOrField>]
	go doc [<pkg>[@<version>].]<sym>[.<methodOrField>]
	go doc [<pkg>[@<version>].][<sym>.]<methodOrField>

Use Cases

• display the documentation of a package before installing it as a module dependency
• display the documentation of a package in another version than the one installed, while planning for an upgrade. This is particularly useful when working on an upgrade with breaking changes, such as a major version upgrade.
• display the documentation of a symbol in a newer/older version of its module: go doc <pkg>@<version>.<sym>
• display the package documentation of a GOBIN tool independently of the current Go context
• display the package documentation of an installed tool (tool in go.mod) in a newer version (ex: @latest)

Rationale

Currently the only builtin ways to display the go doc of a package in a different version that the local Go context (go.mod or GOPATH) are:

• use a local checkout of the repository of that module in the needed version and run go doc from the module directory. This requires to manually find the repository location and manually download the code, while the content may already be present in the Go module cache. (this is how I do it since the GOPATH days)
• read online at https://pkg.go.dev and select the needed version with the @<version> suffix in the URL
• the undocumented way (in fact I invented it while writing this proposal):

$ go mod download <module>@<version>
$ go doc "$(go env GOMODCACHE)"/<module>@<version>[/<pkg-relative-to-module>]

Example for github.com/dolmen-go/sqlar/sqlarfs@v0.2.0:

$ go mod download github.com/dolmen-go/sqlar@v0.2.0
$ go doc "$(go env GOMODCACHE)/github.com/dolmen-go/sqlar@v0.2.0/sqlarfs"

go run and go install support the <pkg>@<version> syntax that allows to manipulate a package in a module independently of the local Go context. go doc should have the same support for consistency.