Skip to content

/ go

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

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
Labels
FrozenDueToAge
Milestone
Unplanned

Comments

@fordhurley
Copy link

@fordhurley fordhurley commented Sep 17, 2015

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
@matttproud @adg
tools/cmd/vet: Create vet checks for examples.
a25a8d5 
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

@fordhurley fordhurley commented Sep 18, 2015

Proposed fix: https://go-review.googlesource.com/14760
@gopherbot
Copy link

@gopherbot gopherbot commented Sep 18, 2015

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.
Assignees
No one assigned
Labels
FrozenDueToAge
Projects
None yet
Milestone
Unplanned
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants
@fordhurley @ianlancetaylor @gopherbot