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

cmd/vet: validation of example suffixes is too strict #12663

Closed
fordhurley opened this issue Sep 17, 2015 · 2 comments
Closed

cmd/vet: validation of example suffixes is too strict #12663

fordhurley opened this issue Sep 17, 2015 · 2 comments

Comments

@fordhurley
Copy link

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-06f3d45de583663b5ce0fc789861061fR21

The documentation for testing states only that

The suffix must start with a lower-case letter.

In 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 in sort are a good example of these. In fact, I believe that sort will fail go vet as is.

I suggest changing the isExampleSuffix check to check only the first rune with unicode.IsLower.

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>
@ianlancetaylor ianlancetaylor modified the milestones: Unreleased, Unplanned Sep 17, 2015
@ianlancetaylor ianlancetaylor changed the title x/tools/cmd/vet: validation of example suffixes is too strict cmd/vet: validation of example suffixes is too strict Sep 17, 2015
@fordhurley
Copy link
Author

Proposed fix: https://go-review.googlesource.com/14760

@gopherbot
Copy link

CL https://golang.org/cl/14760 mentions this issue.

@golang golang locked and limited conversation to collaborators Sep 22, 2016
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

3 participants