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)).

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.

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

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

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.

Based on the discussion above, this proposal seems like a likely accept.
— rsc for the proposal review group

go doc would change to accept an @version suffix on its first argument, so these all become valid:

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

No change in consensus, so accepted. 🎉
This issue now tracks the work of implementing the proposal.
— rsc for the proposal review group

go doc would change to accept an @version suffix on its first argument, so these all become valid:

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