testableexamples 
Linter checks if examples are testable (have an expected output).
Author of idea is Jamie Tanna (see this issue).
Description
Example functions without output comments are compiled but not executed by go test, see doc.
It means that such examples are not validated. This can lead to outdated code.
That’s why the linter complains on missing output.
func Example_bad() { // <- linter will complain on missing output
fmt.Println("hello")
}
func Example_good() {
fmt.Println("hello")
// Output: hello
}
Usage
The best way is to use golangci-lint. It includes testableexamples and a lot of other great linters.
Install
See official site.
Enable
testableexamples is disabled by default.
To enable it, add the following to your .golangci.yml:
linters:
enable:
testableexamples
Run
golangci-lint run
Directive //nolint:testableexamples
Here is incorrect usage of //nolint directive.
golangci-lint understands it correctly, but godoc will include comment to the code.
// Description
func Example_nolintIncorrect() { //nolint:testableexamples // that's why
fmt.Println("hello")
}
Here are two examples of correct usage of //nolint directive.
godoc will ignore comment.
//nolint:testableexamples // that's why
func Example_nolintCorrect() {
fmt.Println("hello")
}
// Description
//
//nolint:testableexamples // that's why
func Example_nolintCorrectWithDescription() {
fmt.Println("hello")
}
Usage as standalone linter
Install
go install github.com/maratori/testableexamples@latest
Run
testableexamples ./...
Nolint
Standalone linter doesn’t support //nolint directive.
And there is no alternative for that, please use golangci-lint.
