Include newest diagnostics and lints

Author: parlough

src/_data/linter_rules.json

@@ -450,6 +450,17 @@
     "details": "**AVOID** throwing exceptions in finally blocks.\n\nThrowing exceptions in finally blocks will inevitably cause unexpected behavior\nthat is hard to debug.\n\n**BAD:**\n```dart\nclass BadThrow {\n  double nonCompliantMethod() {\n    try {\n      print('hello world! ${1 / 0}');\n    } catch (e) {\n      print(e);\n    } finally {\n      throw 'Find the hidden error :P'; // LINT\n    }\n  }\n}\n```\n\n**GOOD:**\n```dart\nclass Ok {\n  double compliantMethod() {\n    var i = 5;\n    try {\n      i = 1 / 0;\n    } catch (e) {\n      print(e); // OK\n    }\n    return i;\n  }\n}\n```\n\n",
     "sinceDartSdk": "2.0.0"
   },
+  {
+    "name": "unintended_html_in_doc_comment",
+    "description": "Use of angle brackets in a doc comment is treated as HTML by Markdown.",
+    "group": "errors",
+    "state": "stable",
+    "incompatible": [],
+    "sets": [],
+    "fixStatus": "needsEvaluation",
+    "details": "**DO** reference only in-scope identifiers in doc comments.\n\nWhen a developer writes a reference with angle brackets within a doc comment,\nthe angle brackets are interpreted as HTML. The text within pairs of opening and\nclosing angle brackets generally get swallowed by the browser, and will not be\ndisplayed.\n\nWrap text with angle brackets within a code block or within a code span, unless\nthey are delimiters for a Markdown autolink. You can also replace `<` with\n`&lt;` and `>` with `&gt;`.\n\n**BAD:**\n```dart\n/// Text List<int>.\n/// Text [List<int>].\n/// <assignment> -> <variable> = <expression>\n```\n\n**GOOD:**\n```dart\n/// Text `List<int>`.\n/// `<assignment> -> <variable> = <expression>`\n/// <http://foo.bar.baz>\n```\n\n",
+    "sinceDartSdk": "3.4.0-wip"
+  },
   {
     "name": "unnecessary_statements",
     "description": "Avoid using unnecessary statements.",
@@ -2195,13 +2206,13 @@
   },
   {
     "name": "require_trailing_commas",
-    "description": "Use trailing commas for all function calls and declarations.",
+    "description": "Use trailing commas for all parameter lists and argument lists.",
     "group": "style",
     "state": "stable",
     "incompatible": [],
     "sets": [],
     "fixStatus": "hasFix",
-    "details": "**DO** use trailing commas for all function calls and declarations unless the\nfunction call or definition, from the start of the function name up to the\nclosing parenthesis, fits in a single line.\n\n**BAD:**\n```dart\nvoid run() {\n  method('does not fit on one line',\n      'test test test test test test test test test test test');\n}\n```\n\n**GOOD:**\n```dart\nvoid run() {\n  method(\n    'does not fit on one line',\n    'test test test test test test test test test test test',\n  );\n}\n```\n\n**EXCEPTION:** If the final parameter/argument is positional (vs named) and is\neither a function literal implemented using curly braces, a literal map, a\nliteral set or a literal array. This exception only applies if the final\nparameter does not fit entirely on one line.\n\n**NOTE:** This lint rule assumes `dart format` has been run over the code and\nmay produce false positives until that has happened.\n\n",
+    "details": "**DO** use trailing commas for all multi-line parameter lists and argument\nlists. A parameter list or argument list that fits on one line, including the\nopening parenthesis and closing parenthesis, does not require a trailing comma.\n\n**BAD:**\n```dart\nvoid run() {\n  method('does not fit on one line',\n      'test test test test test test test test test test test');\n}\n```\n\n**GOOD:**\n```dart\nvoid run() {\n  method(\n    'does not fit on one line',\n    'test test test test test test test test test test test',\n  );\n}\n```\n\n**EXCEPTION:** If the final argument in an argument list is positional (vs\nnamed) and is either a function literal with curly braces, a map literal, a set\nliteral, or a list literal, then a trailing comma is not required.\nThis exception only applies if the final argument does not fit entirely on one\nline.\n\n**NOTE:** This lint rule assumes that code has been formatted with `dart format`\nand may produce false positives on unformatted code.\n\n",
     "sinceDartSdk": "2.14.0"
   },
   {
@@ -2478,6 +2489,17 @@
     "details": "**DO** use library directives if you want to document a library and/or annotate \na library.\n\n**BAD:**\n```dart\nlibrary;\n```\n\n**GOOD:**\n```dart\n/// This library does important things\nlibrary;\n```\n\n```dart\n@TestOn('js')\nlibrary;\n```\n\nNOTE: Due to limitations with this lint, libraries with parts will not be\nflagged for unnecessary library directives.\n",
     "sinceDartSdk": "2.19.0"
   },
+  {
+    "name": "unnecessary_library_name",
+    "description": "Don't have a library name in a `library` declaration.",
+    "group": "style",
+    "state": "stable",
+    "incompatible": [],
+    "sets": [],
+    "fixStatus": "hasFix",
+    "details": "**DON'T** have a library name in a `library` declaration.\n\nLibrary names are not necessary.\n\nA library does not need a library declaration, but one can be added to attach\nlibrary documentation and library metadata to. A declaration of `library;` is\nsufficient for those uses.\n\nThe only *use* of a library name is for a `part` file to refer back to its\nowning library, but part files should prefer to use a string URI to refer back\nto the library file, not a library name.\n\nIf a library name is added to a library declaration, it introduces the risk of\nname *conflicts*. It's a compile-time error if two libraries in the same program\nhave the same library name. To avoid that, library names tend to be long,\nincluding the package name and path, just to avoid accidental name clashes. That\nmakes such library names hard to read, and not even useful as documentation.\n\n**BAD:**\n```dart\n/// This library has a long name.\nlibrary magnificator.src.helper.bananas;\n```\n\n```dart\nlibrary utils; // Not as verbose, but risks conflicts.\n```\n\n**GOOD:**\n```dart\n/// This library is awesome.\nlibrary;\n\npart \"apart.dart\"; // contains: `part of \"good_library.dart\";`\n```\n",
+    "sinceDartSdk": "3.4.0-wip"
+  },
   {
     "name": "unnecessary_new",
     "description": "Unnecessary new keyword.",

src/content/tools/diagnostic-messages.md

@@ -5341,17 +5341,17 @@ class C {}
 
 ### enum_constant_same_name_as_enclosing
 
-_The name of the enum constant can't be the same as the enum's name._
+_The name of the enum value can't be the same as the enum's name._
 
 #### Description
 
-The analyzer produces this diagnostic when an enum constant has the same
-name as the enum in which it's declared.
+The analyzer produces this diagnostic when an enum value has the same name
+as the enum in which it's declared.
 
 #### Example
 
-The following code produces this diagnostic because the enum constant `E`
-has the same name as the enclosing enum `E`:
+The following code produces this diagnostic because the enum value `E` has
+the same name as the enclosing enum `E`:
 
 ```dart
 enum E {
@@ -5383,14 +5383,14 @@ _The invoked constructor isn't a 'const' constructor._
 
 #### Description
 
-The analyzer produces this diagnostic when an enum constant is being
-created using either a factory constructor or a generative constructor
-that isn't marked as being `const`.
+The analyzer produces this diagnostic when an enum value is being created
+using either a factory constructor or a generative constructor that isn't
+marked as being `const`.
 
 #### Example
 
-The following code produces this diagnostic because the enum constant `e`
-is being initialized by a factory constructor:
+The following code produces this diagnostic because the enum value `e` is
+being initialized by a factory constructor:
 
 ```dart
 enum E {
@@ -5422,8 +5422,8 @@ _Mixins applied to enums can't have instance variables._
 
 The analyzer produces this diagnostic when a mixin that's applied to an
 enum declares one or more instance variables. This isn't allowed because
-the enum constants are constant, and there isn't any way for the
-constructor in the enum to initialize any of the mixin's fields.
+the enum values are constant, and there isn't any way for the constructor
+in the enum to initialize any of the mixin's fields.
 
 #### Example
 
@@ -10959,7 +10959,7 @@ E f() => const [!E!](2);
 
 #### Common fixes
 
-If there's an enum constant with the same value, or if you add such a
+If there's an enum value with the same value, or if you add such a
 constant, then reference the constant directly:
 
 ```dart
@@ -11306,6 +11306,59 @@ extension E on String {
 }
 ```
 
+### invalid_use_of_do_not_submit_member
+
+_Uses of '{0}' should not be submitted to source control._
+
+#### Description
+
+The analyzer produces this diagnostic when a member that is annotated with
+[`@doNotSubmit`][meta-doNotSubmit] is referenced outside of a member
+declaration that is also annotated with `@doNotSubmit`.
+
+#### Example
+
+Given a file `a.dart` containing the following declaration:
+
+```dart
+import 'package:meta/meta.dart';
+
+@doNotSubmit
+void emulateCrash() { /* ... */ }
+```
+
+The following code produces this diagnostic because the declaration is
+being referenced outside of a member that is also annotated with
+`@doNotSubmit`:
+
+```dart
+import 'a.dart';
+
+void f() {
+  [!emulateCrash!]();
+}
+```
+
+#### Common fixes
+
+Most commonly, when complete with local testing, the reference to the
+member should be removed.
+
+If building additional functionality on top of the member, annotate the
+newly added member with `@doNotSubmit` as well:
+
+```dart
+import 'package:meta/meta.dart';
+
+import 'a.dart';
+
+@doNotSubmit
+void emulateCrashWithOtherFunctionality() {
+  emulateCrash();
+  // do other things.
+}
+```
+
 ### invalid_use_of_internal_member
 
 _The member '{0}' can only be used within its package._
@@ -12607,7 +12660,7 @@ must be handled.
 
 #### Example
 
-The following code produces this diagnostic because the enum constant `e2`
+The following code produces this diagnostic because the enum value `e2`
 isn't handled:
 
 ```dart
@@ -21289,8 +21342,8 @@ _There's no constant named '{0}' in '{1}'._
 
 #### Description
 
-The analyzer produces this diagnostic when it encounters an identifier that
-appears to be the name of an enum constant, and the name either isn't
+The analyzer produces this diagnostic when it encounters an identifier
+that appears to be the name of an enum value, and the name either isn't
 defined or isn't visible in the scope in which it's being referenced.
 
 #### Example
@@ -21333,11 +21386,11 @@ _The enum doesn't have an unnamed constructor._
 #### Description
 
 The analyzer produces this diagnostic when the constructor invoked to
-initialize an enum constant doesn't exist.
+initialize an enum value doesn't exist.
 
 #### Examples
 
-The following code produces this diagnostic because the enum constant `c`
+The following code produces this diagnostic because the enum value `c`
 is being initialized by the unnamed constructor, but there's no unnamed
 constructor defined in `E`:
 
@@ -21349,9 +21402,9 @@ enum E {
 }
 ```
 
-The following code produces this diagnostic because the enum constant `c`
-is being initialized by the constructor named `x`, but there's no
-constructor named `x` defined in `E`:
+The following code produces this diagnostic because the enum value `c` is
+being initialized by the constructor named `x`, but there's no constructor
+named `x` defined in `E`:
 
 ```dart
 enum E {
@@ -21363,9 +21416,9 @@ enum E {
 
 #### Common fixes
 
-If the enum constant is being initialized by the unnamed constructor and
-one of the named constructors should have been used, then add the name of
-the constructor:
+If the enum value is being initialized by the unnamed constructor and one
+of the named constructors should have been used, then add the name of the
+constructor:
 
 ```dart
 enum E {
@@ -21375,8 +21428,8 @@ enum E {
 }
 ```
 
-If the enum constant is being initialized by the unnamed constructor and
-none of the named constructors are appropriate, then define the unnamed
+If the enum value is being initialized by the unnamed constructor and none
+of the named constructors are appropriate, then define the unnamed
 constructor:
 
 ```dart
@@ -21387,9 +21440,9 @@ enum E {
 }
 ```
 
-If the enum constant is being initialized by a named constructor and one
-of the existing constructors should have been used, then change the name
-of the constructor being invoked (or remove it if the unnamed constructor
+If the enum value is being initialized by a named constructor and one of
+the existing constructors should have been used, then change the name of
+the constructor being invoked (or remove it if the unnamed constructor
 should be used):
 
 ```dart
@@ -21401,9 +21454,9 @@ enum E {
 }
 ```
 
-If the enum constant is being initialized by a named constructor and none
-of the existing constructors should have been used, then define a
-constructor with the name that was used:
+If the enum value is being initialized by a named constructor and none of
+the existing constructors should have been used, then define a constructor
+with the name that was used:
 
 ```dart
 enum E {
@@ -23448,7 +23501,7 @@ _A member named 'values' can't be declared in an enum._
 #### Description
 
 The analyzer produces this diagnostic when an enum declaration defines a
-member named `values`, whether the member is an enum constant, an instance
+member named `values`, whether the member is an enum value, an instance
 member, or a static member.
 
 Any such member conflicts with the implicit declaration of the static
@@ -23721,14 +23774,14 @@ given._
 
 #### Description
 
-The analyzer produces this diagnostic when an enum constant in an enum
-that has type parameters is instantiated and type arguments are provided,
-but the number of type arguments isn't the same as the number of type
+The analyzer produces this diagnostic when an enum value in an enum that
+has type parameters is instantiated and type arguments are provided, but
+the number of type arguments isn't the same as the number of type
 parameters.
 
 #### Example
 
-The following code produces this diagnostic because the enum constant `c`
+The following code produces this diagnostic because the enum value `c`
 provides one type argument even though the enum `E` is declared to have
 two type parameters: