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

proposal: testing: relax lower-case suffix requirement for example test annotation #43528

Open
kortschak opened this issue Jan 5, 2021 · 0 comments
Labels
Projects
Milestone

Comments

@kortschak
Copy link
Contributor

@kortschak kortschak commented Jan 5, 2021

Background

The testing package provides a mechanism to produce distinct examples for a single package, function, type or method.

Multiple example functions for a package/type/function/method may be provided by appending a distinct suffix to the name. The suffix must start with a lower-case letter.

func Example_suffix() { ... }
func ExampleF_suffix() { ... }
func ExampleT_suffix() { ... }
func ExampleT_M_suffix() { ... }

Currently, this is specified to be defined by a suffix that starts with a lower-case letter. This restrictions is presumably to ensure that a method (which must start with an upper-case letter to be justified in having a documentation example by virtue of being exported) is distinguishable from a suffix tag. The godoc command has always allowed numeric and first characters, enabling the use of culturally conventional numbered examples and use of 'words' that start with a number (see #43454 for the motivation for this proposal). It's worth noting that the only requirement for distinguishing between a method _M and a human-directed _suffix would be that the suffix can not be interpretable as a method worth documenting; it must not have an upper-case initial.

Proposal

Relax the documented restriction to be "The suffix must not start with an upper-case letter."

@gopherbot gopherbot added this to the Proposal milestone Jan 5, 2021
@ianlancetaylor ianlancetaylor added this to Incoming in Proposals Jan 5, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
Proposals
Incoming
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants