Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
kortschak opened this issue Dec 31, 2020 · 8 comments
Open

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

kortschak opened this issue Dec 31, 2020 · 8 comments
Labels
Documentation help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone
Backlog

Comments

@kortschak
Copy link
Contributor

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
@toothrot toothrot added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jan 5, 2021
@toothrot toothrot added this to the Backlog milestone Jan 5, 2021
@bcmills
Copy link
Contributor

bcmills commented Jan 5, 2021

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
Copy link
Contributor

bcmills commented Jan 5, 2021

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
Copy link
Contributor Author

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

@bcmills
Copy link
Contributor

bcmills commented Jan 5, 2021

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

@bcmills bcmills changed the title cmd/{godoc,vet},testing: godoc disagrees with the docs and vet about validity of example name suffixes reprise x/tools/cmd/godoc: godoc associates Example functions that have suffixes rejected by cmd/vet and go/doc Jan 5, 2021
@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Jan 5, 2021
@bcmills bcmills changed the title x/tools/cmd/godoc: godoc associates Example functions that have suffixes rejected by cmd/vet and go/doc x/tools/cmd/godoc,gddo: godoc associates Example functions that have suffixes rejected by cmd/vet and go/doc Jan 5, 2021
@kortschak
Copy link
Contributor Author

kortschak commented Jan 5, 2021 •
edited

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 bcmills changed the title x/tools/cmd/godoc,gddo: godoc associates Example functions that have suffixes rejected by cmd/vet and go/doc x/tools/godoc,gddo: godoc associates Example functions that have suffixes rejected by cmd/vet and go/doc Jan 5, 2021
@bcmills
Copy link
Contributor

bcmills commented Jan 5, 2021 •
edited

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
Copy link
Contributor Author

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,

@kortschak kortschak mentioned this issue Jan 5, 2021
Open
@julieqiu
Copy link
Member

julieqiu commented Jan 6, 2021

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

@bcmills bcmills mentioned this issue Jan 7, 2021
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
5 participants
@toothrot @kortschak @bcmills @julieqiu @gopherbot