cmd/go: go doc does not mention comparable in interface docs

[rogpeppe]

Go version

go version go1.26-devel_29d43df8ab Tue Oct 21 14:49:13 2025 -0700 linux/amd64

Output of go env in your module/workspace:

AR='ar'
CC='gcc'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='g++'
GCCGO='gccgo'
GO111MODULE=''
GOAMD64='v1'
GOARCH='amd64'
GOAUTH='netrc'
GOBIN=''
GOCACHE='/home/rogpeppe/.cache/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/no-home/.config/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=$WORK/.tmp/go-build559787703=/tmp/go-build -gno-record-gcc-switches'
GOHOSTARCH='amd64'
GOHOSTOS='linux'
GOINSECURE=''
GOMOD='/dev/null'
GOMODCACHE='$WORK/.gopath/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='linux'
GOPATH='$WORK/.gopath'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/home/rogpeppe/go'
GOSUMDB='sum.golang.org'
GOTELEMETRY='local'
GOTELEMETRYDIR='/no-home/.config/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/home/rogpeppe/go/pkg/tool/linux_amd64'
GOVCS=''
GOVERSION='go1.26-devel_29d43df8ab Tue Oct 21 14:49:13 2025 -0700'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

I ran this testscript:

exec go doc -all
stdout comparable
-- test.go --
package test

type I interface {
	comparable
	X()
}

type S[T I] struct{}

What did you see happen?

> exec go doc -all
[stdout]
package test // import "."


TYPES

type I interface {
	X()
	// Has unexported methods.
}

type S[T I] struct{}

> stdout comparable
FAIL: /tmp/x.txtar:2: no match for `comparable` found in stdout

What did you expect to see?

I'd expect to see some mention of the comparable constraint in the go doc output, as it's an important (and publicly visible) constraint that the caller has to observe. Also, the "Has unexported methods" comment in inaccurate: the interface does not in fact contain any unexported methods.

[mknyszek]

CC @golang/command-line @griesemer

[adonovan]

This should be an easy fix along the lines of:

--- a/src/cmd/go/internal/doc/pkg.go
+++ b/src/cmd/go/internal/doc/pkg.go
@@ -947,10 +947,11 @@ func trimUnexportedFields(fields *ast.FieldList, isInterface bool) *ast.FieldLis
                        constraint := false
                        switch ident := ty.(type) {
                        case *ast.Ident:
-                               if isInterface && ident.Name == "error" && ident.Obj == nil {
+                               if isInterface && ident.Obj == nil &&
+                                       (ident.Name == "error" || ident.Name == "comparable") {
                                        // For documentation purposes, we consider the builtin error
-                                       // type special when embedded in an interface, such that it
-                                       // always gets shown publicly.
+                                       // and comparable types special when embedded in an interface,
+                                       // such that they always get shown publicly.
                                        list = append(list, field)
                                        continue
                                }

[gopherbot]

Change https://go.dev/cl/727100 mentions this issue: cmd/go: show comparable in go doc interface output