proposal: cmd/go: add `-test` to `go doc`

[thatnealpatel]

Proposal Details

In #17509, @rsc rejected this exact proposal:

Godoc is about showing the exported API from
a package. Test files are not part of the
exported API.

go doc has since greatly expanded in both its
intended scope alongside its unintended consumers,
namely large language models. The evolution of
go doc convinces me it's worth revisiting:

Merged	CL	Change
2015	https://go.dev/cl/9227	go doc
2015	https://go.dev/cl/11953	-cmd
2018	https://go.dev/cl/140959	-src
2018	https://go.dev/cl/141977	-all
2019	https://go.dev/cl/184017	-short
2025	https://go.dev/cl/628175	-http (#68106)
2026	https://go.dev/cl/445116	-ex (#26715)
open	https://go.dev/cl/334876	-json (#34293)

go doc provides deterministic access to
information that is otherwise a few tool
calls, potentially with network round trips
as well. For LLM agents, it also provides
more token efficient output.

While I cannot prove this conjecture to be
true, I propose that we add a -test flag
to go doc.

Proposal

go doc -test [package] [symbol]

When specified, include symbols from *_test.go.
Both *_test packages and non-test packages with
testing symbols are in scope.

It composes with existing flags:

• -test -src: full source of test declarations
• -test -u: unexported test-file symbols
• -test -all: test symbols in the full listing

Without -test, the go doc behavior is unchanged.

Examples

% go doc -test crypto/mlkem
package mlkem // import "crypto/mlkem"

Package mlkem implements the quantum-resistant key encapsulation method ML-KEM
(formerly known as Kyber), as specified in NIST FIPS 203.

Most applications should use the ML-KEM-768 parameter set, as implemented by
DecapsulationKey768 and EncapsulationKey768.

[NIST FIPS 203]: https://doi.org/10.6028/NIST.FIPS.203

const SharedKeySize = 32 ...
type DecapsulationKey1024 struct{ ... }
    func GenerateKey1024() (*DecapsulationKey1024, error)
    func NewDecapsulationKey1024(seed []byte) (*DecapsulationKey1024, error)
type DecapsulationKey768 struct{ ... }
    func GenerateKey768() (*DecapsulationKey768, error)
    func NewDecapsulationKey768(seed []byte) (*DecapsulationKey768, error)
type EncapsulationKey1024 struct{ ... }
    func NewEncapsulationKey1024(encapsulationKey []byte) (*EncapsulationKey1024, error)
type EncapsulationKey768 struct{ ... }
    func NewEncapsulationKey768(encapsulationKey []byte) (*EncapsulationKey768, error)

package mlkem_test // external test package

func BenchmarkDecaps(b *testing.B)
func BenchmarkEncaps(b *testing.B)
func BenchmarkKeyGen(b *testing.B)
func BenchmarkRoundTrip(b *testing.B)
func Bob(encapsulationKey []byte) (ciphertext []byte)
func Example()
func TestAccumulated(t *testing.T)
func TestBadLengths(t *testing.T)
func TestConstantSizes(t *testing.T)
func TestRoundTrip(t *testing.T)

% go doc -src -test crypto/mlkem BenchmarkKeyGen
package mlkem_test // external test package

func BenchmarkKeyGen(b *testing.B) {
        var d, z [32]byte
        rand.Read(d[:])
        rand.Read(z[:])
        b.ResetTimer()
        for i := 0; i < b.N; i++ {
                dk := mlkem.GenerateKeyInternal768(&d, &z)
                sink ^= dk.EncapsulationKey().Bytes()[0]
        }
}

/cc @golang/proposal-review

[gopherbot]

Change https://go.dev/cl/774341 mentions this issue: cmd/go/internal/doc: add -test flag

[gabyhelp]

Related Issues

• x/tools/cmd/godoc: generate docs for test files #17509 (closed)
• cmd/doc: print example code and output #56073 (closed)
• proposal: go/doc,testing: add playable examples using a *testing.T context #74009 (closed)
• cmd/doc: confusing error message when directory only contains test package #32044 (closed)
• cmd/go: doc: "go doc pkg.Func" doesn't search in defining package whose path has form "example.com/pkg-go/v2" #76248
• cmd/godoc: document package-level examples #5807 (closed)
• proposal: go doc: add `-tags` flag for selecting fileset to show documentation for #77774 (closed)
• proposal: cmd/go: allow versioned go doc commands #73489 (closed)

Related Code Changes

• cmd/go,cmd/doc: add "go doc"
• cmd/go: add example support to go doc output

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[hyangah]

Is the main goal to use go doc to read the source code of test files efficiently? (Usually TestXX, BenchmarkXX, ExampleXX functions don't have much comments as function signatures.)

What will be different from gopls's clis?

[thatnealpatel]

@hyangah The primary use is -src and -u. However, @adonovan did mention a use-case for encouraging large/complex tests to document at the TestXX and BenchmarkXX leve.

I did not write this with much consideration of the gopls CLI (perhaps I should?)

I've found that LLMs will sometimes reach for grep or awk if go doc is not "generally" easier.

You can of course override this using markdown files; however, as models get more powerful, there's a reasonable argument that minimizing herding markdown is better. My bet is that by adding the last "functional gap," go doc becomes more "blessed" inside these blackboxes by default.

[dmitshur]

https://go.dev/doc/comment documents the concept of "Go doc comments" and how to write them. Go users who are looking to document exported APIs rely on the mechanisms there because it has effect on tools that interpreted doc comments, including go doc itself, pkg.go.dev, and potentially others. There's currently no well defined concept of doc comments for _test.go files (though there's a reasonable extension of treating tests/benchmarks/fuzz targets as top-level functions). I want to point out that adding support in the go doc tool for something that wasn't documented as a convention can result in some churn, as existing comments that had one interpretation or style would potentially start being seen differently if go doc starts accessing them. It may also invite a follow up proposal to extend the doc.Package API to provide programmatic access to the same things go doc -test would show, and a feature request to pkg.go.dev to display identifiers from _test.go files.

It also sounds like the -test flag isn't intended to help with go doc's goal to "show the exported API from a package". If the proposed functionality can be offered in a separate dedicated command, it wouldn't need to live in the main Go repository like cmd/go does. That would also mean its release cycle could differ from that of the main Go repository (a major release every 6 months), and also to potentially make breaking changes with comparative easy while its declared as v0. So have you considered if it could work well to make this a separate command that behaves like the proposed go doc -test would?

[thatnealpatel]

@dmitshur Valid points; I expected (but hoped otherwise) that
this proposal might hit the graveyard.

A standalone tool would be self-defeating for the proposal's
arguably thin value proposition. And, I included the history of
go doc's API expansion to challenge the "show the exported
API from a package" argument: -src, -u, and -cmd.

If this could invite further divergence and fracture go doc's
philosophy, I think it's reasonable to close this proposal.