cmd/vet: validation of example suffixes is too strict #12663
Closed
Labels
Milestone
Comments
fordhurley
referenced
this issue
in golang/tools
Sep 17, 2015
In spite of https://blog.golang.org/examples and http://golang.org/pkg/testing/#pkg-examples, a number of internal Go authors have found writing documentation examples to be problematic in the sense that the syntax is error-prone due to loose coupling with identifiers found in the source corpus. This commit introduces a suite of validations for documentation examples: Overall: - Correct suffices, if present - Niladic function argument and return signatures func Example() {} func ExampleF() {} - F exists func ExampleT() {} - T exists func ExampleT_M() {} - T exists - M exists within T Further, if the example is in `package foo_test`, vet attempts to resolve the respective lookups in `package foo`, if `package foo` exists (cf., `package stringutil_test`). Change-Id: Ifa13906363541ebf28325681b749b14b7f8b103d Reviewed-on: https://go-review.googlesource.com/11982 Reviewed-by: Andrew Gerrand <adg@golang.org>
Proposed fix: https://go-review.googlesource.com/14760 |
CL https://golang.org/cl/14760 mentions this issue. |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
go vet
has an error in the way it validates the suffix on examples. Currently, the tool requires that suffixes are entirely lowercase. See: golang/tools@a25a8d5#diff-06f3d45de583663b5ce0fc789861061fR21The documentation for
testing
states only thatIn fact,
godoc
will translate the first character of the suffix to uppercase when building the html and leave the rest as is. Because of this, camelCase suffixes are the only way to have "multi-word" names for examples. The package examples insort
are a good example of these. In fact, I believe thatsort
will failgo vet
as is.I suggest changing the
isExampleSuffix
check to check only the first rune withunicode.IsLower
.The text was updated successfully, but these errors were encountered: