Feature request: a way to nolint a file without it ending up in godoc #892
Labels
Comments
|
I ran into this due to another weird feature. I am using go:generate enumer to get string values from comments - and I get a misspell linter warning on the comment. Since I can't // nolint:misspell the comment itself, I want to add it for the whole file. |
|
Instead of using the directive, you can use |
|
The directives golang/go@5a550b6#diff-f56160fd9fcea272966a8a1d692ad9f49206fdd8dbcbfe384865a98cd9bc2749R158 |
|
This comment works fine for me: |
abhinav
added a commit
to pulumi/pulumi
that referenced
this issue
Jan 6, 2023
Go treats comments that match the following regex as directives.
//[a-z0-9]+:[a-z0-9]
Comments that are directives don't show in an entity's documentation.
golang/go@5a550b6#diff-f56160fd9fcea272966a8a1d692ad9f49206fdd8dbcbfe384865a98cd9bc2749R165
Our code has `//nolint` directives that now show in the API Reference.
This is because these directives are in one of the following forms,
which don't get this special treatment.
// nolint:foo
//nolint: foo
This change fixes all such directives found by the regex:
`// nolint|//nolint: `.
See bottom of commit for command used for the fix.
Verification:
Here's the output of `go doc` on some entities
before and after this change.
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
nolint: lll, interfacer
nolint: lll, interfacer
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
```
After
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
func BoolRef(v bool) *bool
func Float64Ref(v float64) *float64
func IntRef(v int) *int
func IsSecret(o Output) bool
```
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine. nolint: revive
```
After:
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine.
```
Note that golangci-lint offers a 'nolintlint' linter
that finds such miuses of nolint,
but it also finds other issues so I've deferred that to a follow up PR.
Resolves #11785
Related: golangci/golangci-lint#892
[git-generate]
FILES=$(mktemp)
rg -l '// nolint|//nolint: ' |
tee "$FILES" |
xargs perl -p -i -e '
s|// nolint|//nolint|g;
s|//nolint: |//nolint:|g;
'
rg '.go$' < "$FILES" | xargs gofmt -w -s
abhinav
added a commit
to pulumi/pulumi
that referenced
this issue
Jan 6, 2023
Go treats comments that match the following regex as directives.
//[a-z0-9]+:[a-z0-9]
Comments that are directives don't show in an entity's documentation.
golang/go@5a550b6#diff-f56160fd9fcea272966a8a1d692ad9f49206fdd8dbcbfe384865a98cd9bc2749R165
Our code has `//nolint` directives that now show in the API Reference.
This is because these directives are in one of the following forms,
which don't get this special treatment.
// nolint:foo
//nolint: foo
This change fixes all such directives found by the regex:
`// nolint|//nolint: `.
See bottom of commit for command used for the fix.
Verification:
Here's the output of `go doc` on some entities
before and after this change.
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
nolint: lll, interfacer
nolint: lll, interfacer
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
```
After
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
func BoolRef(v bool) *bool
func Float64Ref(v float64) *float64
func IntRef(v int) *int
func IsSecret(o Output) bool
```
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine. nolint: revive
```
After:
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine.
```
Note that golangci-lint offers a 'nolintlint' linter
that finds such miuses of nolint,
but it also finds other issues so I've deferred that to a follow up PR.
Resolves #11785
Related: golangci/golangci-lint#892
[git-generate]
FILES=$(mktemp)
rg -l '// nolint|//nolint: ' |
tee "$FILES" |
xargs perl -p -i -e '
s|// nolint|//nolint|g;
s|//nolint: |//nolint:|g;
'
rg '.go$' < "$FILES" | xargs gofmt -w -s
bors bot
added a commit
to pulumi/pulumi
that referenced
this issue
Jan 6, 2023
11791: sdk/go: Remove 'nolint' directives from package docs r=abhinav a=abhinav
# Description
Go treats comments that match the following regex as directives.
//[a-z0-9]+:[a-z0-9]
Comments that are directives don't show in an entity's documentation.
golang/go@5a550b6#diff-f56160fd9fcea272966a8a1d692ad9f49206fdd8dbcbfe384865a98cd9bc2749R165
Our code has `//nolint` directives that now show in the API Reference.
This is because these directives are in one of the following forms,
which don't get this special treatment.
// nolint:foo
//nolint: foo
This change fixes all such directives found by the regex:
`// nolint|//nolint: `.
See bottom of commit for command used for the fix.
# Verification
Here's the output of `go doc` on some entities
before and after this change.
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
nolint: lll, interfacer
nolint: lll, interfacer
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
```
After
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
func BoolRef(v bool) *bool
func Float64Ref(v float64) *float64
func IntRef(v int) *int
func IsSecret(o Output) bool
```
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine. nolint: revive
```
After:
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine.
```
# Follow-up
Note that golangci-lint offers a 'nolintlint' linter
that finds such misuses of nolint,
but it also finds other problems so I've deferred those to a separate PR.
Resolves #11785
Related: golangci/golangci-lint#892
```
[git-generate]
FILES=$(mktemp)
rg -l '// nolint|//nolint: ' |
tee "$FILES" |
xargs perl -p -i -e '
s|// nolint|//nolint|g;
s|//nolint: |//nolint:|g;
'
rg '.go$' < "$FILES" | xargs gofmt -w -s
```
Co-authored-by: Abhinav Gupta <abhinav@pulumi.com>
bors bot
added a commit
to pulumi/pulumi
that referenced
this issue
Jan 6, 2023
11791: sdk/go: Remove 'nolint' directives from package docs r=abhinav a=abhinav
# Description
Go treats comments that match the following regex as directives.
//[a-z0-9]+:[a-z0-9]
Comments that are directives don't show in an entity's documentation.
golang/go@5a550b6#diff-f56160fd9fcea272966a8a1d692ad9f49206fdd8dbcbfe384865a98cd9bc2749R165
Our code has `//nolint` directives that now show in the API Reference.
This is because these directives are in one of the following forms,
which don't get this special treatment.
// nolint:foo
//nolint: foo
This change fixes all such directives found by the regex:
`// nolint|//nolint: `.
See bottom of commit for command used for the fix.
# Verification
Here's the output of `go doc` on some entities
before and after this change.
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
nolint: lll, interfacer
nolint: lll, interfacer
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
```
After
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
func BoolRef(v bool) *bool
func Float64Ref(v float64) *float64
func IntRef(v int) *int
func IsSecret(o Output) bool
```
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine. nolint: revive
```
After:
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine.
```
# Follow-up
Note that golangci-lint offers a 'nolintlint' linter
that finds such misuses of nolint,
but it also finds other problems so I've deferred those to a separate PR.
Resolves #11785
Related: golangci/golangci-lint#892
```
[git-generate]
FILES=$(mktemp)
rg -l '// nolint|//nolint: ' |
tee "$FILES" |
xargs perl -p -i -e '
s|// nolint|//nolint|g;
s|//nolint: |//nolint:|g;
'
rg '.go$' < "$FILES" | xargs gofmt -w -s
```
Co-authored-by: Abhinav Gupta <abhinav@pulumi.com>
abhinav
added a commit
to pulumi/pulumi
that referenced
this issue
Jan 6, 2023
Go treats comments that match the following regex as directives.
//[a-z0-9]+:[a-z0-9]
Comments that are directives don't show in an entity's documentation.
golang/go@5a550b6#diff-f56160fd9fcea272966a8a1d692ad9f49206fdd8dbcbfe384865a98cd9bc2749R165
Our code has `//nolint` directives that now show in the API Reference.
This is because these directives are in one of the following forms,
which don't get this special treatment.
// nolint:foo
//nolint: foo
This change fixes all such directives found by the regex:
`// nolint|//nolint: `.
See bottom of commit for command used for the fix.
Verification:
Here's the output of `go doc` on some entities
before and after this change.
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
nolint: lll, interfacer
nolint: lll, interfacer
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
```
After
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
func BoolRef(v bool) *bool
func Float64Ref(v float64) *float64
func IntRef(v int) *int
func IsSecret(o Output) bool
```
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine. nolint: revive
```
After:
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine.
```
Note that golangci-lint offers a 'nolintlint' linter
that finds such miuses of nolint,
but it also finds other issues so I've deferred that to a follow up PR.
Resolves #11785
Related: golangci/golangci-lint#892
[git-generate]
FILES=$(mktemp)
rg -l '// nolint|//nolint: ' |
tee "$FILES" |
xargs perl -p -i -e '
s|// nolint|//nolint|g;
s|//nolint: |//nolint:|g;
'
rg '.go$' < "$FILES" | xargs gofmt -w -s
bors bot
added a commit
to pulumi/pulumi
that referenced
this issue
Jan 6, 2023
11791: sdk/go: Remove 'nolint' directives from package docs r=abhinav a=abhinav
# Description
Go treats comments that match the following regex as directives.
//[a-z0-9]+:[a-z0-9]
Comments that are directives don't show in an entity's documentation.
golang/go@5a550b6#diff-f56160fd9fcea272966a8a1d692ad9f49206fdd8dbcbfe384865a98cd9bc2749R165
Our code has `//nolint` directives that now show in the API Reference.
This is because these directives are in one of the following forms,
which don't get this special treatment.
// nolint:foo
//nolint: foo
This change fixes all such directives found by the regex:
`// nolint|//nolint: `.
See bottom of commit for command used for the fix.
# Verification
Here's the output of `go doc` on some entities
before and after this change.
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
nolint: lll, interfacer
nolint: lll, interfacer
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
```
After
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi | head -n8
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
const EnvOrganization = "PULUMI_ORGANIZATION" ...
var ErrPlugins = errors.New("pulumi: plugins requested")
func BoolRef(v bool) *bool
func Float64Ref(v float64) *float64
func IntRef(v int) *int
func IsSecret(o Output) bool
```
Before
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine. nolint: revive
```
After:
```
% go doc github.com/pulumi/pulumi/sdk/v3/go/pulumi URN_
package pulumi // import "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
func URN_(o string) ResourceOption
URN_ is an optional URN of a previously-registered resource of this type to
read from the engine.
```
# Follow-up
Note that golangci-lint offers a 'nolintlint' linter
that finds such misuses of nolint,
but it also finds other problems so I've deferred those to a separate PR.
Resolves #11785
Related: golangci/golangci-lint#892
```
[git-generate]
FILES=$(mktemp)
rg -l '// nolint|//nolint: ' |
tee "$FILES" |
xargs perl -p -i -e '
s|// nolint|//nolint|g;
s|//nolint: |//nolint:|g;
'
rg '.go$' < "$FILES" | xargs gofmt -w -s
```
Co-authored-by: Abhinav Gupta <abhinav@pulumi.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
To nolint an entire file, we can do
But godoc wants us to do something different there: it uses that space for a package doc-comment. This means that the nolint ends up in the package's godoc, which is undesirable as it's irrelevant to users. (And, depending on lint settings, it may cause further lint errors as it's not exactly a style-compliant package doc-comment.)
So it seems to me like there would be a use in a different way to nolint the entire file. (Of course you can do so in
.golangci.yml, but that's not right next to you when reading the file; it means you have to update it if you move the file; etc.) Sadly, I don't see an ideal alternative, but maybe one could say it can go after the package line, or anywhere near the top and use some other mechanism to make it clear that it applies to the whole file (//nolint-file:linter-name, say).The text was updated successfully, but these errors were encountered: