x/tools/godoc,gddo: godoc associates Example functions that have suffixes rejected by cmd/vet and go/doc

[kortschak]

What version of Go are you using (go version)?

$ go version
go version devel +2ff33f5e44 Thu Dec 17 16:03:19 2020 +0000 linux/amd64

Does this issue reproduce with the latest release?

Yes.

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
go version devel +2ff33f5e44 Thu Dec 17 16:03:19 2020 +0000 linux/amd64
GO111MODULE="on"
GOARCH="amd64"
GOBIN="/home/user/bin"
GOCACHE="/home/user/.cache/go-build"
GOENV="/home/user/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/home/user/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/user"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/user/go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/user/go/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="devel +2ff33f5e44 Thu Dec 17 16:03:19 2020 +0000"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/dev/null"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build3281173737=/tmp/go-build -gno-record-gcc-switches"

What did you do?

~/src/gonum.org/v1/gonum/graph/topo$ go vet

gonum.org/v1/gonum/graph/topo_test

./2sat_example_test.go:177:1: ExampleTarjanSCC_2sat refers to unknown field or method: TarjanSCC.2sat

However, godoc renders the 2sat example.

What did you expect to see?

An error from vet and a failure from godoc to render the example or no error from vet and a godoc rendering of the example.

What did you see instead?

A vet error but a rendered example. See for example the godoc.org page here (note that pkg.go.dev does not render this example).

What would you like to see?

No error and a rendered example. That is, a relaxation of the documented requirement for an initial lowercase letter in the suffix ("The suffix must start with a lower-case letter.") to allow numeric leading glyphs.

Additional information

This is a repeat of #27442 which was closed into #23864 with comments there that this motivating issue would be considered in the fix. The change that that issue links to does not fix this problem consistently (local godoc does render the example, godoc.org also, but — in my view unreasonably stricly — pkg.go.dev does not). The documentation does say "The suffix must start with a lower-case letter." However given the rationale for that being a way of disambiguating methods' examples (which must start with an uppercase due to language rules) the requirement seems overly strict; it could be anything that is not a method, that is !uppercase as stated here.

/cc @dmitshur

[bcmills]

There is no cmd/godoc package. Do you mean go/doc, cmd/doc, golang.org/x/tools/godoc (the standalone godoc HTTP server), or github.com/golang/gddo/gddo-server (the server backing godoc.org)?

[bcmills]

Since you say this doesn't reproduce on pkg.go.dev, I suspect that the bug is in github.com/golang/gddo/gddo-server.

[kortschak]

Yes, sorry, x/tools/cmd/godoc.

[bcmills]

@julieqiu, are the x/pkgsite folks maintaining x/tools/cmd/godoc at this point in time?

[kortschak]

Just to be clear, IMO the issue would be better fixed by relaxing the strictness of the vet check and testing docs, not the implementation of godoc. This does not look like the direction that is being taken.

[bcmills]

The suffix requirements are documented in the testing package and encoded in at least the go/doc package, and probably other tools as well.

The inconsistency between x/tools/godoc and cmd/doc is a bug in one of those two packages, and that's easy to fix.

Relaxing the behavior of those tools — along with other (unspecified, perhaps third-party) tools that currently rely on the documented requirements — seems like a much bigger task. That should probably go through the proposal process.

[kortschak]

This advice would have been helpful 2 years ago.

The behaviour of example test annotation has been consistent since it was introduced, godoc has always accepted numeric prefixed tags,

[julieqiu]

@bcmills re: #43454 (comment), @dmitshur is the current owner of x/tools/godoc.

[seankhliao]

I believe pkgsite doesn't have this issue.