@@ -4,6 +4,7 @@ Linter checks if examples are testable (have an expected output).
44
55> Author of idea is [ Jamie Tanna] ( https://github.com/jamietanna ) (see [ this issue] ( https://github.com/golangci/golangci-lint/issues/3084 ) ).
66
7+
78## Description
89
910Example functions without output comments are compiled but not executed by ` go test ` , see [ doc] ( https://pkg.go.dev/testing#hdr-Examples ) .
@@ -22,6 +23,62 @@ func Example_good() {
2223```
2324
2425
26+ ## Usage
27+
28+ The best way is to use [ golangci-lint] ( https://golangci-lint.run/ ) .
29+ It includes [ testableexamples] ( https://golangci-lint.run/usage/linters/#list-item-testableexamples ) and a lot of other great linters.
30+
31+ ### Install
32+
33+ See [ official site] ( https://golangci-lint.run/usage/install/ ) .
34+
35+ ### Enable
36+
37+ ` testableexamples ` is disabled by default.
38+ To enable it, add the following to your ` .golangci.yml ` :
39+
40+ ``` yaml
41+ linters :
42+ enable :
43+ testableexamples
44+ ` ` `
45+
46+ ### Run
47+
48+ ` ` ` shell
49+ golangci-lint run
50+ ```
51+
52+ ### Directive ` //nolint:testableexamples `
53+
54+ Here is incorrect usage of ` //nolint ` directive.
55+ ` golangci-lint ` understands it correctly, but ` godoc ` will include comment to the code.
56+
57+ ``` go
58+ // Description
59+ func Example_nolintIncorrect () { // nolint:testableexamples // that's why
60+ fmt.Println (" hello" )
61+ }
62+ ```
63+
64+ Here are two examples of correct usage of ` //nolint ` directive.
65+ ` godoc ` will ignore comment.
66+
67+ ``` go
68+ // nolint:testableexamples // that's why
69+ func Example_nolintCorrect () {
70+ fmt.Println (" hello" )
71+ }
72+
73+ // Description
74+ //
75+ // nolint:testableexamples // that's why
76+ func Example_nolintCorrectWithDescription () {
77+ fmt.Println (" hello" )
78+ }
79+ ```
80+
81+
2582## Usage as standalone linter
2683
2784### Install
@@ -35,6 +92,16 @@ go install github.com/maratori/testableexamples@latest
3592testableexamples ./...
3693```
3794
95+ ### Nolint
96+
97+ Standalone linter doesn't support ` //nolint ` directive.
98+ And there is no alternative for that, please use ` golangci-lint ` .
99+
100+
101+ ## License
102+
103+ [ MIT License] [ license-url ]
104+
38105
39106[ ci-img ] : https://github.com/maratori/testableexamples/actions/workflows/ci.yml/badge.svg
40107[ ci-url ] : https://github.com/maratori/testableexamples/actions/workflows/ci.yml
0 commit comments