Skip to content

Commit a808950

Browse files
authored
Add usage via golangci-lint to readme (#11)
1 parent 4819803 commit a808950

1 file changed

Lines changed: 67 additions & 0 deletions

File tree

README.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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

910
Example 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
3592
testableexamples ./...
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

Comments
 (0)