lint: update ignore directives manual (#1285)

Author: bartlomieju

go.json

@@ -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/",

runtime/reference/cli/lint.md

@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.