cmd/{godoc,vet},testing: godoc disagrees with the docs and vet about validity of example name suffixes

[kortschak]

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

$ go version
go version go1.11 linux/amd64

Does this issue reproduce with the latest release?

Yes.

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

linux/amd64

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: 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.

What did you see instead?

A vet error but a rendered 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.

[agnivade]

The title of the issue suggests that the issue is with godoc. But it seems you want the documented behavior itself to allow numeric characters. In which case, this should be a proposal issue because what you are suggesting is a behavior change. I think allowing numerical characters deviates from our existing language spec, which forces all identifiers to start with a letter (https://tip.golang.org/ref/spec#identifier).

IMO, we should fix godoc to be consistent with the docs and with vet. According to current behavior, godoc should just ignore any examples which do not match the example name rule.

[kortschak]

The formulation of the bug is what it is because there are three moving parts here, the testing package documentation, the current godoc behaviour and the current vet behaviour; maybe the prefix should be "cmd/{godoc,vet},testing:".

I don't agree that the spec comes into play in this (with a caveat below) as the suffix is not a language-level identifier, it's essentially a human-directed comment hidden in an identifier. Where the spec does come in is that the suffix must not be interpretable as an exported method since then godoc would attempt and fail to find a place to put it or would place it in the wrong location. Interestingly, vet does not have a problem with the M part of a types example test pointing to an exported field, although that will not ever be rendered.

So, the issue is complicated, but could be simple. But, it seems to me that a proposal is more complicated than is warranted here.

[dsnet]

The problem is that the example syntax is fundamentally ambiguous and ideally all the tools should be consistent about how they resolve that ambiguity (although there is technically no ambiguity in this specific case due to the leading digit). Unfortunately, currently each tool has their own copy of the example parsing logic, and handles this case differently.

I brought up this issue in #23864. Having a unified implementation of example parsing should resolve this problem. Perhaps we close this as a duplicate of that one?

[kortschak]

I'm happy for this to be closed and subsumed into that. What I would like to be considered though is the rule mentioned above; it does not need to be a lowercase initial, it just needs to not be an uppercase initial.

[dsnet]

The challenge is that the logic for godoc.org also treats the suffix as anything without an uppercase (thus includes numbers), so we'll probably need to update the documentation in the testing package to match what has pragmatically been the current state of affairs.