Go 1.27 Teaches go doc the @version Suffix: Inspect Package APIs Without Touching go.modBrief · digest for November 21
Brief≈ 1 min

Go 1.27 Teaches go doc the @version Suffix: Inspect Package APIs Without Touching go.mod

It's a familiar annoyance: you want to check the API of an external library or a newer release, and go doc complains that the package isn't in your project. You had to open pkg.go.dev or temporarily pollute go.mod. Go 1.27 fixes this—go doc now accepts a @version suffix on its first argument.

If that version isn't on disk yet, Go downloads it into your local module cache (GOMODCACHE) without touching your go.mod.

# Docs for the latest version of a package
go doc go.starlark.net/syntax@latest

# Specific symbol as the second argument
go doc golang.org/x/tools/txtar@v0.13.0 FS

# Or dot notation, with @version strictly at the end
go doc golang.org/x/tools/txtar.FS@v0.13.0

Writing txtar@v0.13.0.FS won't work—the version must go at the very end of the first argument. Go 1.27 also adds the -ex flag to go doc to list runnable examples.

This idea from proposal #63696 was originally slated for Go 1.23, but Russ Cox held it back because a clean implementation required reworking the command's internals. Just remember that go doc pkg@version only reads the API and doesn't check project compatibility—once you add the dependency, still run your build and go test ./....

Want a deep diveVotes help us choose what to break down in detail. This material has 0 votes.
Sources · 3