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

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

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

Comments

Assignees
No one assigned
Labels
FrozenDueToAge
Projects
None yet
Milestone
  Unplanned
3 participants
@fordhurley @gopherbot @ianlancetaylor
@fordhurley
Copy link

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

@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

This comment has been minimized.

Sign in to view
Copy link
Author

commented Sep 18, 2015

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

This comment has been minimized.

Sign in to view
Copy link

commented Sep 18, 2015

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

@adg adg closed this in golang/tools@0ced849 Sep 21, 2015

@golang golang locked and limited conversation to collaborators Sep 22, 2016

@gopherbot gopherbot added the FrozenDueToAge label Sep 22, 2016

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.