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

lint: update ignore directives manual #1285

Merged
merged 3 commits into from
Dec 21, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions go.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
"ide": "/runtime/getting_started/setup_your_environment/#setting-up-your-editor%2Fide",
"import_maps": "/runtime/manual/basics/import_maps",
"info": "/runtime/manual/tools/info",
"lint-ignore": "/runtime/reference/cli/lint/#ignore-directives",
"lint": "/runtime/manual/tools/lint",
"lsp": "/runtime/reference/cli/lsp",
"permissions": "/runtime/fundamentals/security/",
Expand Down
63 changes: 54 additions & 9 deletions runtime/reference/cli/lint.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,9 @@ For a complete list of supported rules, visit

## Ignore directives

### Files
### File level

To ignore the whole file, a `// deno-lint-ignore-file` directive should placed
at the top of the file:
To ignore a whole file use `// deno-lint-ignore-file` at the top of the file:

```ts
// deno-lint-ignore-file
Expand All @@ -28,7 +27,7 @@ function foo(): any {
}
```

or
You can also specify the reason for ignoring the file:

```ts
// deno-lint-ignore-file -- reason for ignoring
Expand All @@ -41,7 +40,7 @@ function foo(): any {
The ignore directive must be placed before the first statement or declaration:

```ts
// Copyright 2020 the Deno authors. All rights reserved. MIT license.
// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.

/**
* Some JS doc
Expand All @@ -66,11 +65,25 @@ function foo(): any {
}
```

### Diagnostics
If there are multiple `// deno-lint-ignore-file` directives, all but the first
one are ignored:

To ignore certain diagnostics, the `// deno-lint-ignore <rules...>` directive
should be placed before the targeted line. Specifying the ignored rule name is
required:
```ts
// This is effective
// deno-lint-ignore-file no-explicit-any no-empty

// But this is NOT effective
// deno-lint-ignore-file no-debugger

function foo(): any {
debugger; // not ignored!
}
```

### Line level

To ignore specific diagnostics use `// deno-lint-ignore <codes...>` on the
preceding line of the offending line.

```ts
// deno-lint-ignore no-explicit-any
Expand All @@ -84,6 +97,8 @@ function bar(a: any) {
}
```

You must specify the names of the rules to be ignored.

You can also specify the reason for ignoring the diagnostic:

```ts
Expand All @@ -92,3 +107,33 @@ function foo(): any {
// ...
}
```

## Ignore `ban-unused-ignore` itself

`deno lint` provides [`ban-unused-ignore` rule](/lint/rules/ban-unused-ignore/),
which will detect ignore directives that don't ever suppress certain
diagnostics. This is useful when you want to discover ignore directives that are
no longer necessary after refactoring the code.

In a few cases, however, you might want to ignore `ban-unused-ignore` rule
itself. One of the typical cases would be when working with auto-generated
files; it makes sense to add file-level ignore directives for some rules, and
there's almost no need for detecting unused directives via `ban-unused-ignore`
in this case.

You can use `// deno-lint-ignore-file ban-unused-ignore` as always if you want
to suppress the rule for a whole file:

```ts
// deno-lint-ignore-file ban-unused-ignore no-explicit-any

// `no-explicit-any` isn't used but you'll get no diagnostics because of ignoring
// `ban-unused-ignore`
console.log(42);
```

Do note that ignoring `ban-unused-ignore` itself only works via file-level
ignore directives. This means that per line directives, like
`// deno-lint-ignore ban-unused-ignore`, don't work at all. If you want to
ignore `ban-unused-ignore` for some special reasons, make sure to add it as a
file-level ignore directive.
Loading