Add docs for new lint rules (#6376)

src/_data/linter_rules.json

@@ -2797,6 +2797,19 @@
     "details": "**DON'T** use angle-bracketed text, `<…>`, in a doc comment unless you want to\nwrite an HTML tag or link.\n\nMarkdown allows HTML tags as part of the Markdown code, so you can write, for\nexample, `T<sub>1</sub>`. Markdown does not restrict the allowed tags, it just\nincludes the tags verbatim in the output.\n\nDartdoc only allows some known and valid HTML tags, and will omit any disallowed\nHTML tag from the output. See the list of allowed tags and directives below.\nYour doc comment should not contain any HTML tags that are not on this list.\n\nMarkdown also allows you to write an \"auto-link\" to an URL as for example\n`<https://example.com/page.html>`, delimited only by `<...>`. Such a link is\nallowed by Dartdoc as well.\nA `<...>` delimited text is an auto-link if it is a valid absolute URL, starting\nwith a scheme of at least two characters followed by a colon, like\n`<mailto:mr_example@example.com>`.\n\nAny other other occurrence of `<word...>` or `</word...>` is likely a mistake\nand this lint will warn about it.\nIf something looks like an HTML tag, meaning it starts with `<` or `</`\nand then a letter, and it has a later matching `>`, then it's considered an\ninvalid HTML tag unless it is an auto-link, or it starts with an *allowed*\nHTML tag.\n\nSuch a mistake can, for example, happen if writing Dart code with type arguments\noutside of a code span, for example `The type List<int> is ...`, where `<int>`\nlooks like an HTML tag. Missing the end quote of a code span can have the same\neffect: ``The type `List<int> is ...`` will also treat `<int>` as an HTML tag.\n\nAllows the following HTML directives: HTML comments, `<!-- text -->`, processing\ninstructions, `<?...?>`, CDATA-sections, and `<[CDATA...]>`.\nAllows DartDoc links like `[List<int>]` which are not after a `]` or before a\n`[` or `(`, and allows the following recognized HTML tags:\n`a`, `abbr`, `address`, `area`, `article`, `aside`, `audio`, `b`,\n`bdi`, `bdo`, `blockquote`, `br`, `button`, `canvas`, `caption`,\n`cite`, `code`, `col`, `colgroup`, `data`, `datalist`, `dd`, `del`,\n`dfn`, `div`, `dl`, `dt`, `em`, `fieldset`, `figcaption`, `figure`,\n`footer`, `form`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `header`, `hr`,\n`i`, `iframe`, `img`, `input`, `ins`, `kbd`, `keygen`, `label`,\n`legend`, `li`, `link`, `main`, `map`, `mark`, `meta`, `meter`, `nav`,\n`noscript`, `object`, `ol`, `optgroup`, `option`, `output`, `p`,\n`param`, `pre`, `progress`, `q`, `s`, `samp`, `script`, `section`,\n`select`, `small`, `source`, `span`, `strong`, `style`, `sub`, `sup`,\n`table`, `tbody`, `td`, `template`, `textarea`, `tfoot`, `th`, `thead`,\n`time`, `title`, `tr`, `track`, `u`, `ul`, `var`, `video` and `wbr`.\n\n**BAD:**\n```dart\n/// The type List<int>.\n/// <assignment> -> <variable> = <expression>\n```\n\n**GOOD:**\n```dart\n/// The type `List<int>`.\n/// The type [List<int>]\n/// `<assignment> -> <variable> = <expression>`\n/// \\<assignment\\> -> \\<variable\\> = \\<expression\\>`\n/// <http://foo.bar.baz>\n```",
     "sinceDartSdk": "3.5"
   },
+  {
+    "name": "unnecessary_async",
+    "description": "No await no async.",
+    "categories": [
+      "style"
+    ],
+    "state": "experimental",
+    "incompatible": [],
+    "sets": [],
+    "fixStatus": "needsFix",
+    "details": "Functions that don't do `await` don't have to be `async`.\n\nUsually such functions also don't have to return a `Future`, which allows\nan invoker to avoid `await` in its code, etc. Synchronous code in\ngeneral runs faster, and is easier to reason about.\n\n**BAD:**\n```dart\nvoid f() async {\n  // await Future.delayed(const Duration(seconds: 2));\n  print(0);\n}\n```\n\n**GOOD:**\n```dart\nvoid f() {\n  // await Future.delayed(const Duration(seconds: 2));\n  print(0);\n}\n```",
+    "sinceDartSdk": "3.7"
+  },
   {
     "name": "unnecessary_await_in_return",
     "description": "Unnecessary `await` keyword in return.",
@@ -2910,6 +2923,19 @@
     "details": "From [Effective Dart](https://dart.dev/effective-dart/usage#dont-wrap-a-field-in-a-getter-and-setter-unnecessarily):\n\n**AVOID** wrapping fields in getters and setters just to be \"safe\".\n\nIn Java and C#, it's common to hide all fields behind getters and setters (or\nproperties in C#), even if the implementation just forwards to the field.  That\nway, if you ever need to do more work in those members, you can do it without needing\nto touch the callsites.  This is because calling a getter method is different\nthan accessing a field in Java, and accessing a property isn't binary-compatible\nwith accessing a raw field in C#.\n\nDart doesn't have this limitation.  Fields and getters/setters are completely\nindistinguishable.  You can expose a field in a class and later wrap it in a\ngetter and setter without having to touch any code that uses that field.\n\n**BAD:**\n```dart\nclass Box {\n  var _contents;\n  get contents => _contents;\n  set contents(value) {\n    _contents = value;\n  }\n}\n```\n\n**GOOD:**\n```dart\nclass Box {\n  var contents;\n}\n```",
     "sinceDartSdk": "2.0"
   },
+  {
+    "name": "unnecessary_ignore",
+    "description": "Don't ignore a diagnostic code that is not produced.",
+    "categories": [
+      "style"
+    ],
+    "state": "experimental",
+    "incompatible": [],
+    "sets": [],
+    "fixStatus": "hasFix",
+    "details": "**DON'T** specify an ignore for a diagnostic that is not produced.",
+    "sinceDartSdk": "3.8"
+  },
   {
     "name": "unnecessary_lambdas",
     "description": "Don't create a lambda when a tear-off will do.",