cmd/go: `go doc`'s `-all` and `-short` flags don't work together

[cespare]

Go version

go version go1.25.1 linux/amd64

Output of go env in your module/workspace:

not relevant

What did you do?

I ran several commands:

• go doc -all runtime/metrics
• go doc -short runtime/metrics
• go doc -all -short runtime/metrics

What did you see happen?

With -all -short, go doc behaved the exact same way as with just -all. In other words, it seemed to ignore -short entirely and printed out all the documentation text.

What did you expect to see?

I think that -all -short should display the full API without documentation. I was looking for a quick way to get a concise text summary of the API surface and I was surprised that -all -short didn't work.

Alternatively, if -all and -short aren't supposed to work together, that should be documented and the tool should exit with a usage error rather than ignoring -short entirely.

I also filed an issue for a possibly-related -short bug at #77192.

[prattmic]

cc @golang/command-line @robpike

[matloob]

I think we should fix this, but for now let's document that they don't work together. I sent CL 760304 for that.

I've also put together CL 760305 that adds support for combining -all and -short but I'm a little nervous about it because there seem to be a lot of cases that we need to track down to make sure it works properly. It's not completely clear what we should do for instance for the case of, say, the values of runtime/metrics.ValueKind. Here's the current output my CL produces for go doc -short -all runtime/metrics

func Read(m []Sample)
type Description struct{ ... }
func All() []Description
type Float64Histogram struct{ ... }
type Sample struct{ ... }
type Value struct{ ... }
func (v Value) Float64() float64
func (v Value) Float64Histogram() *Float64Histogram
func (v Value) Kind() ValueKind
func (v Value) Uint64() uint64
type ValueKind int
const KindBad ValueKind = iota
const KindUint64
const KindFloat64
const KindFloat64Histogram

[gopherbot]

Change https://go.dev/cl/760304 mentions this issue: cmd/go/internal/doc: document that -all and -short cannot be combined

[gopherbot]

Change https://go.dev/cl/760305 mentions this issue: cmd/go: support go doc -all -short