cmd/doc: support 'go doc package@version' syntax

[adonovan]

The go doc command displays documentation for packages in the workspace, but it would be very useful if it also worked on packages (and commands in particular) that are not part of the workspace, using an @version suffix. The implementation would consult the module cache, populating it as needed. For example:

$ go doc go.starlark.net/syntax@latest
go: downloading go.starlark.net v0.0.0-20231016134836-22325403fcb3
go: added go.starlark.net v0.0.0-20231016134836-22325403fcb3
package syntax // import "go.starlark.net/syntax"

Package syntax provides a Starlark parser and abstract syntax tree.
...

@rsc made the suggestion that the version suffix could be inferred if the package name was not part of the workspace, if it matched the name of a command on $PATH, and that command was a Go executable, and the metadata inside that Go executable provided a module@version provenance string.

[bcmills]

the version suffix could be inferred if the package name was not part of the workspace, if it matched the name of a command on $PATH, and that command was a Go executable, and the metadata inside that Go executable provided a module@version provenance string.

That sounds like an awful lot of magic. 😅

For the specific case of printing a version in a usage string, perhaps we could provide a helper function somewhere that uses runtime/debug.ReadBuildInfo to produce a path@version string for the current binary? That could be used in both a usage message and a --version flag, so that users could run something like go doc $(syntax --version).

Or, perhaps go version itself should have a flag that prints that form? Then users could run go doc $(go version -main $(which syntax)).

[earthboundkid]

For the specific case of printing a version in a usage string, perhaps we could provide a helper function somewhere that uses runtime/debug.ReadBuildInfo to produce a path@version string for the current binary? That could be used in both a usage message and a --version flag, so that users could run something like go doc $(syntax --version).

FWIW, I wrote a module which looks at runtime/debug.ReadBuildInfo for CLI usage screens, but it would be nicer to have it built in somewhere.

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[rsc]

Sounds like this is a likely accept, but the implementation will probably be tricky, so let's leave it for Go 1.23.

[rsc]

I don't think we discussed whether it is possible to add @version to go doc pkg.symbol, and if so how.
I think these two would work:

go doc golang.org/x/tools/txtar.FS@v0.13.0
go doc golang.org/x/tools/txtar@v0.13.0 FS

and this would be rejected:

go doc golang.org/x/tools/txtar@v0.13.0.FS

After more discussion with @bcmills, I've realized that making this change the right way is going to require significant reworking of the existing machinery. Please don't send CLs. We'll take care of it. Thanks.