diff --git a/pkg/analyzer/lib/src/dart/error/hint_codes.g.dart b/pkg/analyzer/lib/src/dart/error/hint_codes.g.dart
index 6f9b09b..435189c 100644
--- a/pkg/analyzer/lib/src/dart/error/hint_codes.g.dart
+++ b/pkg/analyzer/lib/src/dart/error/hint_codes.g.dart
@@ -83,6 +83,31 @@
   /**
    * Users should not assign values marked `@doNotStore`.
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when the value of a function
+  // (including methods and getters) that is explicitly or implicitly marked by
+  // the `[doNotStore][meta-doNotStore]` annotation is stored in either a field
+  // or top-level variable.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the value of the
+  // function `f` is being stored in the top-level variable `x`:
+  //
+  // ```dart
+  // import 'package:meta/meta.dart';
+  //
+  // @doNotStore
+  // int f() => 1;
+  //
+  // var x = [!f()!];
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Replace references to the field or variable with invocations of the
+  // function producing the value.
   static const HintCode ASSIGNMENT_OF_DO_NOT_STORE = HintCode(
     'ASSIGNMENT_OF_DO_NOT_STORE',
     "'{0}' is marked 'doNotStore' and shouldn't be assigned to a field or "
@@ -94,6 +119,39 @@
    * Parameters:
    * 0: the name of the declared return type
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a method or function can
+  // implicitly return `null` by falling off the end. While this is valid Dart
+  // code, it's better for the return of `null` to be explicit.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the function `f`
+  // implicitly returns `null`:
+  //
+  // ```dart
+  // String? [!f!]() {}
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the return of `null` is intentional, then make it explicit:
+  //
+  // ```dart
+  // String? f() {
+  //   return null;
+  // }
+  // ```
+  //
+  // If the function should return a non-null value along that path, then add
+  // the missing return statement:
+  //
+  // ```dart
+  // String? f() {
+  //   return '';
+  // }
+  // ```
   static const HintCode BODY_MIGHT_COMPLETE_NORMALLY_NULLABLE = HintCode(
     'BODY_MIGHT_COMPLETE_NORMALLY_NULLABLE',
     "This function has a nullable return type of '{0}', but ends without "
@@ -461,6 +519,54 @@
   /**
    * No parameters.
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a comment reference (the name
+  // of a declaration enclosed in square brackets in a documentation comment)
+  // uses the keyword `new` to refer to a constructor. This form is deprecated.
+  //
+  // #### Examples
+  //
+  // The following code produces this diagnostic because the unnamed
+  // constructor is being referenced using `new C`:
+  //
+  // ```dart
+  // /// See [[!new!] C].
+  // class C {
+  //   C();
+  // }
+  // ```
+  //
+  // The following code produces this diagnostic because the constructor named
+  // `c` is being referenced using `new C.c`:
+  //
+  // ```dart
+  // /// See [[!new!] C.c].
+  // class C {
+  //   C.c();
+  // }
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If you're referencing a named constructor, then remove the keyword `new`:
+  //
+  // ```dart
+  // /// See [C.c].
+  // class C {
+  //   C.c();
+  // }
+  // ```
+  //
+  // If you're referencing the unnamed constructor, then remove the keyword
+  // `new` and append `.new` after the class name:
+  //
+  // ```dart
+  // /// See [C.new].
+  // class C {
+  //   C.c();
+  // }
+  // ```
   static const HintCode DEPRECATED_NEW_IN_COMMENT_REFERENCE = HintCode(
     'DEPRECATED_NEW_IN_COMMENT_REFERENCE',
     "Using the 'new' keyword in a comment reference is deprecated.",
@@ -866,7 +972,8 @@
   // ```
   //
   // If type arguments shouldn't be required for the class, then mark the class
-  // with the `@optionalTypeArgs` annotation (from `package:meta`):
+  // with the `[optionalTypeArgs][meta-optionalTypeArgs]` annotation (from
+  // `package:meta`):
   static const HintCode IMPORT_DEFERRED_LIBRARY_WITH_LOAD_FUNCTION = HintCode(
     'IMPORT_DEFERRED_LIBRARY_WITH_LOAD_FUNCTION',
     "The imported library defines a top-level function named 'loadLibrary' "
@@ -878,11 +985,46 @@
   );
 
   /**
+   * No parameters.
+   *
    * https://github.com/dart-lang/sdk/issues/44063
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a library that is null safe
+  // imports a library that isn't null safe.
+  //
+  // #### Example
+  //
+  // Given a file named `a.dart` that contains the following:
+  //
+  // ```dart
+  // %uri="lib/a.dart"
+  // // @dart = 2.9
+  //
+  // class A {}
+  // ```
+  //
+  // The following code produces this diagnostic because a library that null
+  // safe is importing a library that isn't null safe:
+  //
+  // ```dart
+  // import [!'a.dart'!];
+  //
+  // A? f() => null;
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If you can migrate the imported library to be null safe, then migrate it
+  // and update or remove the migrated library's language version.
+  //
+  // If you can't migrate the imported library, then the importing library
+  // needs to have a language version that is before 2.12, when null safety was
+  // enabled by default.
   static const HintCode IMPORT_OF_LEGACY_LIBRARY_INTO_NULL_SAFE = HintCode(
     'IMPORT_OF_LEGACY_LIBRARY_INTO_NULL_SAFE',
-    "The library '{0}' is legacy, and should not be imported into a null safe "
+    "The library '{0}' is legacy, and shouldn't be imported into a null safe "
         "library.",
     correctionMessage: "Try migrating the imported library.",
   );
@@ -967,18 +1109,70 @@
    * 0: the name of the annotation
    * 1: the list of valid targets
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when an annotation is applied to a
+  // kind of declaration that it doesn't support.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the `optionalTypeArgs`
+  // annotation isn't defined to be valid for top-level variables:
+  //
+  // ```dart
+  // import 'package:meta/meta.dart';
+  //
+  // @[!optionalTypeArgs!]
+  // int x = 0;
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Remove the annotation from the declaration.
   static const HintCode INVALID_ANNOTATION_TARGET = HintCode(
     'INVALID_ANNOTATION_TARGET',
-    "The annotation '{0}' can only be used on {1}",
+    "The annotation '{0}' can only be used on {1}.",
   );
 
   /**
-   * This hint is generated anywhere where an element annotated with `@internal`
-   * is exported as a part of a package's public API.
-   *
    * Parameters:
    * 0: the name of the element
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a [public library][] exports a
+  // declaration that is marked with the `[internal][meta-internal]`
+  // annotation.
+  //
+  // #### Example
+  //
+  // Given a file named `a.dart` in the `src` directory that contains:
+  //
+  // ```dart
+  // %uri="lib/src/a.dart"
+  // import 'package:meta/meta.dart';
+  //
+  // @internal class One {}
+  // ```
+  //
+  // The following code, when found in a [public library][] produces this
+  // diagnostic because the `export` directive is exporting a name that is only
+  // intended to be used internally:
+  //
+  // ```dart
+  // [!export 'src/a.dart';!]
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the export is needed, then add a `hide` clause to hide the internal
+  // names:
+  //
+  // ```dart
+  // export 'src/a.dart' hide One;
+  // ```
+  //
+  // If the export isn't needed, then remove it.
   static const HintCode INVALID_EXPORT_OF_INTERNAL_ELEMENT = HintCode(
     'INVALID_EXPORT_OF_INTERNAL_ELEMENT',
     "The member '{0}' can't be exported as a part of a package's public API.",
@@ -986,12 +1180,46 @@
   );
 
   /**
-   * This hint is generated anywhere where an element annotated with `@internal`
-   * is exported indirectly as a part of a package's public API.
-   *
    * Parameters:
    * 0: the name of the element
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a [public library][] exports a
+  // top-level function  with a return type or at least one parameter type that
+  // is marked with the `[internal][meta-internal]` annotation.
+  //
+  // #### Example
+  //
+  // Given a file named `a.dart` in the `src` directory that contains the
+  // following:
+  //
+  // ```dart
+  // %uri="lib/src/a.dart"
+  // import 'package:meta/meta.dart';
+  //
+  // @internal
+  // typedef IntFunction = int Function();
+  //
+  // int f(IntFunction g) => g();
+  // ```
+  //
+  // The following code produces this diagnostic because the function `f` has a
+  // parameter of type `IntFunction`, and `IntFunction` is only intended to be
+  // used internally:
+  //
+  // ```dart
+  // [!export 'src/a.dart' show f;!]
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the function must be public, then make all the types in the function's
+  // signature public types.
+  //
+  // If the function doesn't need to be exported, then stop exporting it,
+  // either by removing it from the `show` clause, adding it to the `hide`
+  // clause, or by removing the export.
   static const HintCode INVALID_EXPORT_OF_INTERNAL_ELEMENT_INDIRECTLY =
       HintCode(
     'INVALID_EXPORT_OF_INTERNAL_ELEMENT_INDIRECTLY',
@@ -1010,22 +1238,92 @@
   );
 
   /**
-   * This hint is generated anywhere a @factory annotation is associated with
-   * a method that does not declare a return type.
+   * Parameters:
+   * 0: The name of the method
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a method that is annotated with
+  // the `[factory][meta-factory]` annotation has a return type of `void`.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the method `createC`
+  // is annotated with the `[factory][meta-factory]` annotation but doesn't
+  // return any value:
+  //
+  // ```dart
+  // import 'package:meta/meta.dart';
+  //
+  // class Factory {
+  //   @factory
+  //   void [!createC!]() {}
+  // }
+  //
+  // class C {}
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Change the return type to something other than `void`:
+  //
+  // ```dart
+  // import 'package:meta/meta.dart';
+  //
+  // class Factory {
+  //   @factory
+  //   C createC() => C();
+  // }
+  //
+  // class C {}
+  // ```
   static const HintCode INVALID_FACTORY_METHOD_DECL = HintCode(
     'INVALID_FACTORY_METHOD_DECL',
     "Factory method '{0}' must have a return type.",
   );
 
   /**
-   * This hint is generated anywhere a @factory annotation is associated with
-   * a non-abstract method that can return anything other than a newly allocated
-   * object.
-   *
    * Parameters:
    * 0: the name of the method
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a method that is annotated with
+  // the `[factory][meta-factory]` annotation doesn't return a newly allocated
+  // object.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the method `createC`
+  // returns the value of a field rather than a newly created instance of `C`:
+  //
+  // ```dart
+  // import 'package:meta/meta.dart';
+  //
+  // class Factory {
+  //   C c = C();
+  //
+  //   @factory
+  //   C [!createC!]() => c;
+  // }
+  //
+  // class C {}
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Change the method to return a newly created instance of the return type:
+  //
+  // ```dart
+  // import 'package:meta/meta.dart';
+  //
+  // class Factory {
+  //   @factory
+  //   C createC() => C();
+  // }
+  //
+  // class C {}
+  // ```
   static const HintCode INVALID_FACTORY_METHOD_IMPL = HintCode(
     'INVALID_FACTORY_METHOD_IMPL',
     "Factory method '{0}' doesn't return a newly allocated object.",
@@ -1041,9 +1339,59 @@
   );
 
   /**
-   * This hint is generated anywhere a @internal annotation is associated with
-   * an element found in a package's public API.
+   * No parameters.
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a declaration is annotated with
+  // the `[internal][meta-internal]` annotation and that declaration is either
+  // in a [public library][] or has a private name.
+  //
+  // #### Example
+  //
+  // The following code, when in a [public library][], produces this diagnostic
+  // because the `[internal][meta-internal]` annotation can't be applied to
+  // declarations in a [public library][]:
+  //
+  // ```dart
+  // import 'package:meta/meta.dart';
+  //
+  // [!@internal!]
+  // class C {}
+  // ```
+  //
+  // The following code, whether in a public or internal library, produces this
+  // diagnostic because the `[internal][meta-internal]` annotation can't be
+  // applied to declarations with private names:
+  //
+  // ```dart
+  // import 'package:meta/meta.dart';
+  //
+  // [!@internal!]
+  // class _C {}
+  //
+  // void f(_C c) {}
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the declaration has a private name, then remove the annotation:
+  //
+  // ```dart
+  // class _C {}
+  //
+  // void f(_C c) {}
+  // ```
+  //
+  // If the declaration has a public name and is intended to be internal to the
+  // package, then move the annotated declaration into an internal library (in
+  // other words, a library inside the `src` directory).
+  //
+  // Otherwise, remove the use of the annotation:
+  //
+  // ```dart
+  // class C {}
+  // ```
   static const HintCode INVALID_INTERNAL_ANNOTATION = HintCode(
     'INVALID_INTERNAL_ANNOTATION',
     "Only public elements in a package's private API can be annotated as being "
@@ -1051,20 +1399,36 @@
   );
 
   /**
-   * Invalid Dart language version comments don't follow the specification [1].
-   * If a comment begins with "@dart" or "dart" (letters in any case),
-   * followed by optional whitespace, followed by optional non-alphanumeric,
-   * non-whitespace characters, followed by optional whitespace, followed by
-   * an optional alphabetical character, followed by a digit, then the
-   * comment is considered to be an attempt at a language version override
-   * comment. If this attempted language version override comment is not a
-   * valid language version override comment, it is reported.
-   *
-   * [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+   * No parameters.
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a comment that appears to be an
+  // attempt to specify a language version override doesn't conform to the
+  // requirements for such a comment. For more information, see
+  // [Per-library language version selection](https://dart.dev/guides/language/evolution#per-library-language-version-selection).
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the word `dart` must
+  // be lowercase in such a comment and because there's no equal sign between
+  // the word `dart` and the version number:
+  //
+  // ```dart
+  // [!// @Dart 2.9!]
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the comment is intended to be a language version override, then change
+  // the comment to follow the correct format:
+  //
+  // ```dart
+  // // @dart = 2.9
+  // ```
   static const HintCode INVALID_LANGUAGE_VERSION_OVERRIDE_AT_SIGN = HintCode(
     'INVALID_LANGUAGE_VERSION_OVERRIDE',
-    "The Dart language version override number must begin with '@dart'",
+    "The Dart language version override number must begin with '@dart'.",
     correctionMessage:
         "Specify a Dart language version override with a comment like '// "
         "@dart = 2.0'.",
@@ -1072,21 +1436,12 @@
   );
 
   /**
-   * Invalid Dart language version comments don't follow the specification [1].
-   * If a comment begins with "@dart" or "dart" (letters in any case),
-   * followed by optional whitespace, followed by optional non-alphanumeric,
-   * non-whitespace characters, followed by optional whitespace, followed by
-   * an optional alphabetical character, followed by a digit, then the
-   * comment is considered to be an attempt at a language version override
-   * comment. If this attempted language version override comment is not a
-   * valid language version override comment, it is reported.
-   *
-   * [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+   * No parameters.
    */
   static const HintCode INVALID_LANGUAGE_VERSION_OVERRIDE_EQUALS = HintCode(
     'INVALID_LANGUAGE_VERSION_OVERRIDE',
     "The Dart language version override comment must be specified with an '=' "
-        "character",
+        "character.",
     correctionMessage:
         "Specify a Dart language version override with a comment like '// "
         "@dart = 2.0'.",
@@ -1096,14 +1451,14 @@
   static const HintCode INVALID_LANGUAGE_VERSION_OVERRIDE_GREATER = HintCode(
     'INVALID_LANGUAGE_VERSION_OVERRIDE',
     "The language version override can't specify a version greater than the "
-        "latest known language version: {0}.{1}",
+        "latest known language version: {0}.{1}.",
     correctionMessage: "Try removing the language version override.",
     uniqueName: 'INVALID_LANGUAGE_VERSION_OVERRIDE_GREATER',
   );
 
   static const HintCode INVALID_LANGUAGE_VERSION_OVERRIDE_LOCATION = HintCode(
     'INVALID_LANGUAGE_VERSION_OVERRIDE',
-    "The language version override must be before any declaration or "
+    "The language version override must be specified before any declaration or "
         "directive.",
     correctionMessage:
         "Try moving the language version override to the top of the file.",
@@ -1111,21 +1466,12 @@
   );
 
   /**
-   * Invalid Dart language version comments don't follow the specification [1].
-   * If a comment begins with "@dart" or "dart" (letters in any case),
-   * followed by optional whitespace, followed by optional non-alphanumeric,
-   * non-whitespace characters, followed by optional whitespace, followed by
-   * an optional alphabetical character, followed by a digit, then the
-   * comment is considered to be an attempt at a language version override
-   * comment. If this attempted language version override comment is not a
-   * valid language version override comment, it is reported.
-   *
-   * [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+   * No parameters.
    */
   static const HintCode INVALID_LANGUAGE_VERSION_OVERRIDE_LOWER_CASE = HintCode(
     'INVALID_LANGUAGE_VERSION_OVERRIDE',
     "The Dart language version override comment must be specified with the "
-        "word 'dart' in all lower case",
+        "word 'dart' in all lower case.",
     correctionMessage:
         "Specify a Dart language version override with a comment like '// "
         "@dart = 2.0'.",
@@ -1133,16 +1479,7 @@
   );
 
   /**
-   * Invalid Dart language version comments don't follow the specification [1].
-   * If a comment begins with "@dart" or "dart" (letters in any case),
-   * followed by optional whitespace, followed by optional non-alphanumeric,
-   * non-whitespace characters, followed by optional whitespace, followed by
-   * an optional alphabetical character, followed by a digit, then the
-   * comment is considered to be an attempt at a language version override
-   * comment. If this attempted language version override comment is not a
-   * valid language version override comment, it is reported.
-   *
-   * [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+   * No parameters.
    */
   static const HintCode INVALID_LANGUAGE_VERSION_OVERRIDE_NUMBER = HintCode(
     'INVALID_LANGUAGE_VERSION_OVERRIDE',
@@ -1155,20 +1492,12 @@
   );
 
   /**
-   * Invalid Dart language version comments don't follow the specification [1].
-   * If a comment begins with "@dart" or "dart" (letters in any case),
-   * followed by optional whitespace, followed by optional non-alphanumeric,
-   * non-whitespace characters, followed by optional whitespace, followed by
-   * an optional alphabetical character, followed by a digit, then the
-   * comment is considered to be an attempt at a language version override
-   * comment. If this attempted language version override comment is not a
-   * valid language version override comment, it is reported.
-   *
-   * [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+   * No parameters.
    */
   static const HintCode INVALID_LANGUAGE_VERSION_OVERRIDE_PREFIX = HintCode(
     'INVALID_LANGUAGE_VERSION_OVERRIDE',
-    "The Dart language version override number can't be prefixed with a letter",
+    "The Dart language version override number can't be prefixed with a "
+        "letter.",
     correctionMessage:
         "Specify a Dart language version override with a comment like '// "
         "@dart = 2.0'.",
@@ -1176,22 +1505,13 @@
   );
 
   /**
-   * Invalid Dart language version comments don't follow the specification [1].
-   * If a comment begins with "@dart" or "dart" (letters in any case),
-   * followed by optional whitespace, followed by optional non-alphanumeric,
-   * non-whitespace characters, followed by optional whitespace, followed by
-   * an optional alphabetical character, followed by a digit, then the
-   * comment is considered to be an attempt at a language version override
-   * comment. If this attempted language version override comment is not a
-   * valid language version override comment, it is reported.
-   *
-   * [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+   * No parameters.
    */
   static const HintCode INVALID_LANGUAGE_VERSION_OVERRIDE_TRAILING_CHARACTERS =
       HintCode(
     'INVALID_LANGUAGE_VERSION_OVERRIDE',
     "The Dart language version override comment can't be followed by any "
-        "non-whitespace characters",
+        "non-whitespace characters.",
     correctionMessage:
         "Specify a Dart language version override with a comment like '// "
         "@dart = 2.0'.",
@@ -1199,16 +1519,7 @@
   );
 
   /**
-   * Invalid Dart language version comments don't follow the specification [1].
-   * If a comment begins with "@dart" or "dart" (letters in any case),
-   * followed by optional whitespace, followed by optional non-alphanumeric,
-   * non-whitespace characters, followed by optional whitespace, followed by
-   * an optional alphabetical character, followed by a digit, then the
-   * comment is considered to be an attempt at a language version override
-   * comment. If this attempted language version override comment is not a
-   * valid language version override comment, it is reported.
-   *
-   * [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+   * No parameters.
    */
   static const HintCode INVALID_LANGUAGE_VERSION_OVERRIDE_TWO_SLASHES =
       HintCode(
@@ -1226,8 +1537,8 @@
    */
   // #### Description
   //
-  // The analyzer produces this diagnostic when the `@literal` annotation is
-  // applied to anything other than a const constructor.
+  // The analyzer produces this diagnostic when the `[literal][[meta-literal]]`
+  // annotation is applied to anything other than a const constructor.
   //
   // #### Examples
   //
@@ -1364,12 +1675,40 @@
   );
 
   /**
-   * This hint is generated anywhere where a member annotated with `@internal`
-   * is used outside of the package in which it is declared.
-   *
    * Parameters:
    * 0: the name of the member
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a reference to a declaration
+  // that is annotated with the `[internal][meta-internal]` annotation is found
+  // outside the package containing the declaration.
+  //
+  // #### Example
+  //
+  // Given a package `p` that defines a library containing a declaration marked
+  // with the `[internal][meta-internal]` annotation:
+  //
+  // ```dart
+  // %uri="package:p/src/p.dart"
+  // import 'package:meta/meta.dart';
+  //
+  // @internal
+  // class C {}
+  // ```
+  //
+  // The following code produces this diagnostic because it's referencing the
+  // class `C`, which isn't intended to be used outside the package `p`:
+  //
+  // ```dart
+  // import 'package:p/src/p.dart';
+  //
+  // void f([!C!] c) {}
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Remove the reference to the internal declaration.
   static const HintCode INVALID_USE_OF_INTERNAL_MEMBER = HintCode(
     'INVALID_USE_OF_INTERNAL_MEMBER',
     "The member '{0}' can only be used within its package.",
@@ -1396,8 +1735,9 @@
   // #### Description
   //
   // The analyzer produces this diagnostic when an instance member that is
-  // annotated with `visibleForOverriding` is referenced outside the library in
-  // which it's declared for any reason other than to override it.
+  // annotated with `[visibleForOverriding][meta-visibleForOverriding]` is
+  // referenced outside the library in which it's declared for any reason other
+  // than to override it.
   //
   // #### Example
   //
@@ -1472,8 +1812,9 @@
    */
   // #### Description
   //
-  // The analyzer produces this diagnostic when either the `@visibleForTemplate`
-  // or `@visibleForTesting` annotation is applied to a non-public declaration.
+  // The analyzer produces this diagnostic when either the `visibleForTemplate`
+  // or `[visibleForTesting][meta-visibleForTesting]` annotation is applied to
+  // a non-public declaration.
   //
   // #### Example
   //
@@ -1522,9 +1863,10 @@
   // #### Description
   //
   // The analyzer produces this diagnostic when anything other than a public
-  // instance member of a class is annotated with `visibleForOverriding`.
-  // Because only public instance members can be overridden outside the defining
-  // library, there's no value to annotating any other declarations.
+  // instance member of a class is annotated with
+  // `[visibleForOverriding][meta-visibleForOverriding]`. Because only public
+  // instance members can be overridden outside the defining library, there's
+  // no value to annotating any other declarations.
   //
   // #### Example
   //
@@ -1663,9 +2005,9 @@
   // #### Description
   //
   // The analyzer produces this diagnostic when the superclass constraint of a
-  // mixin is a class from a different package that was marked as `@sealed`.
-  // Classes that are sealed can't be extended, implemented, mixed in, or used
-  // as a superclass constraint.
+  // mixin is a class from a different package that was marked as
+  // `[sealed][meta-sealed]`. Classes that are sealed can't be extended,
+  // implemented, mixed in, or used as a superclass constraint.
   //
   // #### Example
   //
@@ -1712,8 +2054,8 @@
   //
   // The analyzer produces this diagnostic when an immutable class defines one
   // or more instance fields that aren't final. A class is immutable if it's
-  // marked as being immutable using the annotation `@immutable` or if it's a
-  // subclass of an immutable class.
+  // marked as being immutable using the annotation
+  // `[immutable][meta-immutable]` or if it's a subclass of an immutable class.
   //
   // #### Example
   //
@@ -1773,8 +2115,8 @@
   // #### Description
   //
   // The analyzer produces this diagnostic when a method that overrides a method
-  // that is annotated as `@mustCallSuper` doesn't invoke the overridden method
-  // as required.
+  // that is annotated as `[mustCallSuper][meta-mustCallSuper]` doesn't invoke
+  // the overridden method as required.
   //
   // #### Example
   //
@@ -1831,10 +2173,10 @@
   // #### Description
   //
   // The analyzer produces this diagnostic when a constructor that has the
-  // `@literal` annotation is invoked without using the `const` keyword, but all
-  // of the arguments to the constructor are constants. The annotation indicates
-  // that the constructor should be used to create a constant value whenever
-  // possible.
+  // `[literal][meta-literal]` annotation is invoked without using the `const`
+  // keyword, but all of the arguments to the constructor are constants. The
+  // annotation indicates that the constructor should be used to create a
+  // constant value whenever possible.
   //
   // #### Example
   //
@@ -2009,9 +2351,42 @@
   );
 
   /**
-   * This hint indicates that a null literal is null-checked with `!`, but null
-   * is never not null.
+   * No parameters.
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when the null check operator (`!`)
+  // is used on an expression whose value can only be `null`. In such a case
+  // the operator always throws an exception, which likely isn't the intended
+  // behavior.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the function `g` will
+  // always return `null`, which means that the null check in `f` will always
+  // throw:
+  //
+  // ```dart
+  // void f() {
+  //   [!g()!!];
+  // }
+  //
+  // Null g() => null;
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If you intend to always throw an exception, then replace the null check
+  // with an explicit `throw` expression to make the intent more clear:
+  //
+  // ```dart
+  // void f() {
+  //   g();
+  //   throw TypeError();
+  // }
+  //
+  // Null g() => null;
+  // ```
   static const HintCode NULL_CHECK_ALWAYS_FAILS = HintCode(
     'NULL_CHECK_ALWAYS_FAILS',
     "This null-check will always throw an exception because the expression "
@@ -2145,9 +2520,56 @@
   );
 
   /**
-   * Users should not return values marked `@doNotStore` from functions,
-   * methods or getters not marked `@doNotStore`.
+   * Parameters:
+   * 0: the name of the annotated function being invoked
+   * 1: the name of the function containing the return
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a value that is annotated with
+  // the `[doNotStore][meta-doNotStore]` annotation is returned from a method,
+  // getter, or function that doesn't have the same annotation.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the result of invoking
+  // `f` shouldn't be stored, but the function `g` isn't annotated to preserve
+  // that semantic:
+  //
+  // ```dart
+  // import 'package:meta/meta.dart';
+  //
+  // @doNotStore
+  // int f() => 0;
+  //
+  // int g() => [!f()!];
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the value that shouldn't be stored is the correct value to return, then
+  // mark the function with the `[doNotStore][meta-doNotStore]` annotation:
+  //
+  // ```dart
+  // import 'package:meta/meta.dart';
+  //
+  // @doNotStore
+  // int f() => 0;
+  //
+  // @doNotStore
+  // int g() => f();
+  // ```
+  //
+  // Otherwise, return a different value from the function:
+  //
+  // ```dart
+  // import 'package:meta/meta.dart';
+  //
+  // @doNotStore
+  // int f() => 0;
+  //
+  // int g() => 0;
+  // ```
   static const HintCode RETURN_OF_DO_NOT_STORE = HintCode(
     'RETURN_OF_DO_NOT_STORE',
     "'{0}' is annotated with 'doNotStore' and shouldn't be returned unless "
@@ -2955,10 +3377,10 @@
   // #### Description
   //
   // The analyzer produces this diagnostic when a sealed class (one that either
-  // has the `@sealed` annotation or inherits or mixes in a sealed class) is
-  // referenced in either the `extends`, `implements`, or `with` clause of a
-  // class or mixin declaration if the declaration isn't in the same package as
-  // the sealed class.
+  // has the `[sealed][meta-sealed]` annotation or inherits or mixes in a
+  // sealed class) is referenced in either the `extends`, `implements`, or
+  // `with` clause of a class or mixin declaration if the declaration isn't in
+  // the same package as the sealed class.
   //
   // #### Example
   //
@@ -3213,8 +3635,8 @@
   // #### Description
   //
   // The analyzer produces this diagnostic when an annotation of the form
-  // `@UnusedResult.unless(parameterDefined: parameterName)` specifies a
-  // parameter name that isn't defined by the annotated function.
+  // `[UseResult][meta-UseResult].unless(parameterDefined: parameterName)`
+  // specifies a parameter name that isn't defined by the annotated function.
   //
   // #### Example
   //
@@ -3941,16 +4363,16 @@
   // #### Description
   //
   // The analyzer produces this diagnostic when a function annotated with
-  // `useResult` is invoked, and the value returned by that function isn't used.
-  // The value is considered to be used if a member of the value is invoked, if
-  // the value is passed to another function, or if the value is assigned to a
-  // variable or field.
+  // `[useResult][meta-useResult]` is invoked, and the value returned by that
+  // function isn't used. The value is considered to be used if a member of the
+  // value is invoked, if the value is passed to another function, or if the
+  // value is assigned to a variable or field.
   //
   // #### Example
   //
   // The following code produces this diagnostic because the invocation of
   // `c.a()` isn't used, even though the method `a` is annotated with
-  // `useResult`:
+  // `[useResult][meta-useResult]`:
   //
   // ```dart
   // import 'package:meta/meta.dart';
diff --git a/pkg/analyzer/lib/src/error/codes.g.dart b/pkg/analyzer/lib/src/error/codes.g.dart
index 6b15d00..589b294 100644
--- a/pkg/analyzer/lib/src/error/codes.g.dart
+++ b/pkg/analyzer/lib/src/error/codes.g.dart
@@ -3076,10 +3076,34 @@
     correctionMessage: "Try calling a different constructor.",
   );
 
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when the label in a `continue`
+  // statement resolves to a label on a `switch` statement.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the label `l`, used to
+  // label a `switch` statement, is used in the `continue` statement:
+  //
+  // ```dart
+  // void f(int i) {
+  //   l: switch (i) {
+  //     case 0:
+  //       continue [!l!];
+  //   }
+  // }
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Find a different way to achieve the control flow you need; for example, by
+  // introducing a loop that re-executes the `switch` statement.
   static const CompileTimeErrorCode CONTINUE_LABEL_ON_SWITCH =
       CompileTimeErrorCode(
     'CONTINUE_LABEL_ON_SWITCH',
-    "A continue label resolves to switch, must be loop or switch member",
+    "A `continue` label resolves to a `switch` statement, but the label must "
+        "be on a loop or a switch member.",
   );
 
   /**
@@ -3373,14 +3397,49 @@
   /**
    * No parameters.
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when an expression with a value that
+  // is anything other than one of the allowed kinds of values is followed by
+  // type arguments. The allowed kinds of values are:
+  // - generic types,
+  // - generic constructors, and
+  // - generic functions, including top-level functions, static and instance
+  //   members, and local functions.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because `i` is a top-level
+  // variable, which isn't one of the allowed cases:
+  //
+  // ```dart
+  // int i = 1;
+  //
+  // void f() {
+  //   print([!i!]<int>);
+  // }
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the referenced value is correct, then remove the type arguments:
+  //
+  // ```dart
+  // int i = 1;
+  //
+  // void f() {
+  //   print(i);
+  // }
+  // ```
   static const CompileTimeErrorCode DISALLOWED_TYPE_INSTANTIATION_EXPRESSION =
       CompileTimeErrorCode(
     'DISALLOWED_TYPE_INSTANTIATION_EXPRESSION',
     "Only a generic type, generic function, generic instance method, or "
-        "generic constructor can be type instantiated.",
+        "generic constructor can have type arguments.",
     correctionMessage:
-        "Try instantiating the type(s) of a generic type, generic function, "
-        "generic instance method, or generic constructor.",
+        "Try removing the type arguments, or instantiating the type(s) of a "
+        "generic type, generic function, generic instance method, or generic "
+        "constructor.",
   );
 
   /**
@@ -3665,6 +3724,39 @@
     hasPublishedDocs: true,
   );
 
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when an enum constant 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`:
+  //
+  // ```dart
+  // enum E {
+  //   [!E!]
+  // }
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the name of the enum is correct, then rename the constant:
+  //
+  // ```dart
+  // enum E {
+  //   e
+  // }
+  // ```
+  //
+  // If the name of the constant is correct, then rename the enum:
+  //
+  // ```dart
+  // enum F {
+  //   E
+  // }
+  // ```
   static const CompileTimeErrorCode ENUM_CONSTANT_SAME_NAME_AS_ENCLOSING =
       CompileTimeErrorCode(
     'ENUM_CONSTANT_SAME_NAME_AS_ENCLOSING',
@@ -4596,6 +4688,49 @@
     hasPublishedDocs: true,
   );
 
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a field or variable marked with
+  // the keyword `external` has an initializer, or when an external field is
+  // initialized in a constructor.
+  //
+  // #### Examples
+  //
+  // The following code produces this diagnostic because the external field `x`
+  // is assigned a value in an initializer:
+  //
+  // ```dart
+  // class C {
+  //   external int x;
+  //   C() : [!x!] = 0;
+  // }
+  // ```
+  //
+  // The following code produces this diagnostic because the external field `x`
+  // has an initializer:
+  //
+  // ```dart
+  // class C {
+  //   external final int [!x!] = 0;
+  // }
+  // ```
+  //
+  // The following code produces this diagnostic because the external top level
+  // variable `x` has an initializer:
+  //
+  // ```dart
+  // external final int [!x!] = 0;
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Remove the initializer:
+  //
+  // ```dart
+  // class C {
+  //   external final int x;
+  // }
+  // ```
   static const CompileTimeErrorCode EXTERNAL_FIELD_CONSTRUCTOR_INITIALIZER =
       CompileTimeErrorCode(
     'EXTERNAL_WITH_INITIALIZER',
@@ -4978,10 +5113,41 @@
   );
 
   /**
-   * 7.6.1 Generative Constructors: It is a compile-time error if an
-   * initializing formal is used by a function other than a non-redirecting
-   * generative constructor.
+   * No parameters.
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when an initializing formal
+  // parameter is used in the parameter list for anything other than a
+  // constructor.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the initializing
+  // formal parameter `this.x` is being used in the method `m`:
+  //
+  // ```dart
+  // class A {
+  //   int x = 0;
+  //
+  //   m([[!this.x!] = 0]) {}
+  // }
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Replace the initializing formal parameter with a normal parameter and
+  // assign the field within the body of the method:
+  //
+  // ```dart
+  // class A {
+  //   int x = 0;
+  //
+  //   m([int x = 0]) {
+  //     this.x = x;
+  //   }
+  // }
+  // ```
   static const CompileTimeErrorCode FIELD_INITIALIZER_OUTSIDE_CONSTRUCTOR =
       CompileTimeErrorCode(
     'FIELD_INITIALIZER_OUTSIDE_CONSTRUCTOR',
@@ -6134,12 +6300,40 @@
   );
 
   /**
-   * 14.1 Imports: It is a compile-time error if the specified URI of an
-   * immediate import does not refer to a library declaration.
-   *
    * Parameters:
    * 0: the uri pointing to a non-library declaration
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a [part file][] is imported
+  // into a library.
+  //
+  // #### Example
+  //
+  // Given a [part file][] named `part.dart` containing the following:
+  //
+  // ```dart
+  // %uri="lib/part.dart"
+  // part of lib;
+  //
+  // class C{}
+  // ```
+  //
+  // The following code produces this diagnostic because imported files can't
+  // have a part-of directive:
+  //
+  // ```dart
+  // library lib;
+  //
+  // import [!'part.dart'!];
+  //
+  // C c = C();
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Import the library that contains the [part file][] rather than the
+  // [part file][] itself.
   static const CompileTimeErrorCode IMPORT_OF_NON_LIBRARY =
       CompileTimeErrorCode(
     'IMPORT_OF_NON_LIBRARY',
@@ -6245,13 +6439,45 @@
   );
 
   /**
-   * It is a compile-time error if a part file has a different language version
-   * override than its library.
-   *
-   * https://github.com/dart-lang/language/blob/master/accepted/
-   * future-releases/language-versioning/feature-specification.md
-   * #individual-library-language-version-override
+   * No parameters.
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a [part file][] has a language
+  // version override comment that specifies a different language version than
+  // the one being used for the library to which the part belongs.
+  //
+  // #### Example
+  //
+  // Given a [part file][] named `part.dart` that contains the following:
+  //
+  // ```dart
+  // %uri="lib/part.dart"
+  // // @dart = 2.6
+  // part of 'test.dart';
+  // ```
+  //
+  // The following code produces this diagnostic because the parts of a library
+  // must have the same language version as the defining compilation unit:
+  //
+  // ```dart
+  // // @dart = 2.5
+  // part [!'part.dart'!];
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Remove the language version override from the [part file][], so that it
+  // implicitly uses the same version as the defining compilation unit:
+  //
+  // ```dart
+  // part of 'test.dart';
+  // ```
+  //
+  // If necessary, either adjust the language version override in the defining
+  // compilation unit to be appropriate for the code in the part, or migrate
+  // the code in the [part file][] to be consistent with the new language
+  // version.
   static const CompileTimeErrorCode INCONSISTENT_LANGUAGE_VERSION_OVERRIDE =
       CompileTimeErrorCode(
     'INCONSISTENT_LANGUAGE_VERSION_OVERRIDE',
@@ -9287,13 +9513,41 @@
   );
 
   /**
-   * 7.6.1 Generative Constructors: A generative constructor may be redirecting,
-   * in which case its only action is to invoke another generative constructor.
+   * No parameters.
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a constructor redirects to more
+  // than one other constructor in the same class (using `this`).
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the unnamed
+  // constructor in `C` is redirecting to both `this.a` and `this.b`:
+  //
+  // ```dart
+  // class C {
+  //   C() : this.a(), [!this.b()!];
+  //   C.a();
+  //   C.b();
+  // }
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Remove all but one of the redirections:
+  //
+  // ```dart
+  // class C {
+  //   C() : this.a();
+  //   C.a();
+  //   C.b();
+  // }
+  // ```
   static const CompileTimeErrorCode
       MULTIPLE_REDIRECTING_CONSTRUCTOR_INVOCATIONS = CompileTimeErrorCode(
     'MULTIPLE_REDIRECTING_CONSTRUCTOR_INVOCATIONS',
-    "Constructors can have at most one 'this' redirection.",
+    "Constructors can have only one 'this' redirection, at most.",
     correctionMessage: "Try removing all but one of the redirections.",
   );
 
@@ -10492,15 +10746,75 @@
   );
 
   /**
-   * An error code for when a class has no explicit constructor, and therefore
-   * a constructor is implicitly defined which uses a factory as a
-   * superinitializer. See [NON_GENERATIVE_CONSTRUCTOR].
-   *
    * Parameters:
    * 0: the name of the superclass
    * 1: the name of the current class
    * 2: the implicitly called factory constructor of the superclass
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a class has an implicit
+  // generative constructor and the superclass has an explicit unnamed factory
+  // constructor. The implicit constructor in the subclass implicitly invokes
+  // the unnamed constructor in the superclass, but generative constructors can
+  // only invoke another generative constructor, not a factory constructor.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the implicit
+  // constructor in `B` invokes the unnamed constructor in `A`, but the
+  // constructor in `A` is a factory constructor, when a generative constructor
+  // is required:
+  //
+  // ```dart
+  // class A {
+  //   factory A() => throw 0;
+  //   A.named();
+  // }
+  //
+  // class [!B!] extends A {}
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the unnamed constructor in the superclass can be a generative
+  // constructor, then change it to be a generative constructor:
+  //
+  // ```dart
+  // class A {
+  //   A();
+  //   A.named();
+  // }
+  //
+  // class B extends A { }
+  // ```
+  //
+  // If the unnamed constructor can't be a generative constructor and there are
+  // other generative constructors in the superclass, then explicitly invoke
+  // one of them:
+  //
+  // ```dart
+  // class A {
+  //   factory A() => throw 0;
+  //   A.named();
+  // }
+  //
+  // class B extends A {
+  //   B() : super.named();
+  // }
+  // ```
+  //
+  // If there are no generative constructors that can be used and none can be
+  // added, then implement the superclass rather than extending it:
+  //
+  // ```dart
+  // class A {
+  //   factory A() => throw 0;
+  //   A.named();
+  // }
+  //
+  // class B implements A {}
+  // ```
   static const CompileTimeErrorCode NON_GENERATIVE_IMPLICIT_CONSTRUCTOR =
       CompileTimeErrorCode(
     'NON_GENERATIVE_IMPLICIT_CONSTRUCTOR',
@@ -11341,23 +11655,78 @@
   );
 
   /**
-   * User friendly specialized error for [NON_GENERATIVE_CONSTRUCTOR]. This
-   * handles the case of `class E extends Exception` which will never work
-   * because [Exception] has no generative constructors.
-   *
    * Parameters:
    * 0: the name of the subclass
    * 1: the name of the superclass
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a class that has at least one
+  // generative constructor (whether explicit or implicit) has a superclass
+  // that doesn't have any generative constructors. Every generative
+  // constructor, except the one defined in `Object`, invokes, either
+  // explicitly or implicitly, one of the generative constructors from its
+  // superclass.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the class `B` has an
+  // implicit generative constructor that can't invoke a generative constructor
+  // from `A` because `A` doesn't have any generative constructors:
+  //
+  // ```dart
+  // class A {
+  //   factory A.none() => throw '';
+  // }
+  //
+  // class B extends [!A!] {}
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the superclass should have a generative constructor, then add one:
+  //
+  // ```dart
+  // class A {
+  //   A();
+  //   factory A.none() => throw '';
+  // }
+  //
+  // class B extends A {}
+  // ```
+  //
+  // If the subclass shouldn't have a generative constructor, then remove it by
+  // adding a factory constructor:
+  //
+  // ```dart
+  // class A {
+  //   factory A.none() => throw '';
+  // }
+  //
+  // class B extends A {
+  //   factory B.none() => throw '';
+  // }
+  // ```
+  //
+  // If the subclass must have a generative constructor but the superclass
+  // can't have one, then implement the superclass instead:
+  //
+  // ```dart
+  // class A {
+  //   factory A.none() => throw '';
+  // }
+  //
+  // class B implements A {}
+  // ```
   static const CompileTimeErrorCode NO_GENERATIVE_CONSTRUCTORS_IN_SUPERCLASS =
       CompileTimeErrorCode(
     'NO_GENERATIVE_CONSTRUCTORS_IN_SUPERCLASS',
-    "The class '{0}' cannot extend '{1}' because '{1}' only has factory "
+    "The class '{0}' can't extend '{1}' because '{1}' only has factory "
         "constructors (no generative constructors), and '{0}' has at least one "
         "generative constructor.",
     correctionMessage:
         "Try implementing the class instead, adding a generative (not factory) "
-        "constructor to the superclass {0}, or a factory constructor to the "
+        "constructor to the superclass '{1}', or a factory constructor to the "
         "subclass.",
   );
 
@@ -11660,8 +12029,8 @@
   // If the library should be using a different file as a part, then change the
   // URI in the part directive to be the URI of the other file.
   //
-  // If the part file should be a part of this library, then update the URI (or
-  // library name) in the part-of directive to be the URI (or name) of the
+  // If the [part file][] should be a part of this library, then update the URI
+  // (orlibrary name) in the part-of directive to be the URI (or name) of the
   // correct library.
   static const CompileTimeErrorCode PART_OF_DIFFERENT_LIBRARY =
       CompileTimeErrorCode(
@@ -11730,13 +12099,14 @@
   // #### Description
   //
   // The analyzer produces this diagnostic when a library that doesn't have a
-  // `library` directive (and hence has no name) contains a `part` directive and
-  // the `part of` directive in the part file uses a name to specify the library
-  // that it's a part of.
+  // `library` directive (and hence has no name) contains a `part` directive
+  // and the `part of` directive in the [part file][] uses a name to specify
+  // the library that it's a part of.
   //
   // #### Example
   //
-  // Given a part file named `part_file.dart` containing the following code:
+  // Given a [part file][] named `part_file.dart` containing the following
+  // code:
   //
   // ```dart
   // %uri="lib/part_file.dart"
@@ -11744,8 +12114,8 @@
   // ```
   //
   // The following code produces this diagnostic because the library including
-  // the part file doesn't have a name even though the part file uses a name to
-  // specify which library it's a part of:
+  // the [part file][] doesn't have a name even though the [part file][] uses a
+  // name to specify which library it's a part of:
   //
   // ```dart
   // part [!'part_file.dart'!];
@@ -11753,8 +12123,8 @@
   //
   // #### Common fixes
   //
-  // Change the `part of` directive in the part file to specify its library by
-  // URI:
+  // Change the `part of` directive in the [part file][] to specify its library
+  // by URI:
   //
   // ```dart
   // part of 'test.dart';
@@ -11882,19 +12252,57 @@
   );
 
   /**
-   * From the `Static Types` section of the spec:
-   *
-   *     A type T is malformed if:
-   *     - T has the form id or the form prefix.id, and in the enclosing lexical
-   *       scope, the name id (respectively prefix.id) does not denote a type.
-   *
-   * In particular, this means that if an import prefix is shadowed by a local
-   * declaration, it is an error to try to use it as a prefix for a type name.
+   * Parameters:
+   * 0: the prefix being shadowed
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when an import prefix is used in a
+  // context where it isn't visible because it was shadowed by a local
+  // declaration.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the prefix `a` is
+  // being used to access the class `Future`, but isn't visible because it's
+  // shadowed by the parameter `a`:
+  //
+  // ```dart
+  // import 'dart:async' as a;
+  //
+  // a.Future? f(int a) {
+  //   [!a!].Future? x;
+  //   return x;
+  // }
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Rename either the prefix:
+  //
+  // ```dart
+  // import 'dart:async' as p;
+  //
+  // p.Future? f(int a) {
+  //   p.Future? x;
+  //   return x;
+  // }
+  // ```
+  //
+  // Or rename the local variable:
+  //
+  // ```dart
+  // import 'dart:async' as a;
+  //
+  // a.Future? f(int p) {
+  //   a.Future? x;
+  //   return x;
+  // }
+  // ```
   static const CompileTimeErrorCode PREFIX_SHADOWED_BY_LOCAL_DECLARATION =
       CompileTimeErrorCode(
     'PREFIX_SHADOWED_BY_LOCAL_DECLARATION',
-    "The prefix '{0}' can't be used here because it is shadowed by a local "
+    "The prefix '{0}' can't be used here because it's shadowed by a local "
         "declaration.",
     correctionMessage:
         "Try renaming either the prefix or the local declaration.",
@@ -11993,17 +12401,92 @@
     hasPublishedDocs: true,
   );
 
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a private setter is used in a
+  // library where it isn't visible.
+  //
+  // #### Example
+  //
+  // Given a file named `a.dart` that contains the following:
+  //
+  // ```dart
+  // %uri="lib/a.dart"
+  // class A {
+  //   static int _f = 0;
+  // }
+  // ```
+  //
+  // The following code produces this diagnostic because it references the
+  // private setter `_f` even though the setter isn't visible:
+  //
+  // ```dart
+  // import 'a.dart';
+  //
+  // void f() {
+  //   A.[!_f!] = 0;
+  // }
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If you're able to make the setter public, then do so:
+  //
+  // ```dart
+  // %uri="lib/a.dart"
+  // class A {
+  //   static int f = 0;
+  // }
+  // ```
+  //
+  // If you aren't able to make the setter public, then find a different way to
+  // implement the code.
   static const CompileTimeErrorCode PRIVATE_SETTER = CompileTimeErrorCode(
     'PRIVATE_SETTER',
-    "The setter '{0}' is private and can't be accessed outside of the library "
+    "The setter '{0}' is private and can't be accessed outside the library "
         "that declares it.",
     correctionMessage: "Try making it public.",
   );
 
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a final local variable that
+  // isn't initialized at the declaration site is read at a point where the
+  // compiler can't prove that the variable is always initialized before it's
+  // referenced.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the final local
+  // variable `x` is read (on line 3) when it's possible that it hasn't yet
+  // been initialized:
+  //
+  // ```dart
+  // int f() {
+  //   final int x;
+  //   return [!x!];
+  // }
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Ensure that the variable has been initialized before it's read:
+  //
+  // ```dart
+  // int f(bool b) {
+  //   final int x;
+  //   if (b) {
+  //     x = 0;
+  //   } else {
+  //     x = 1;
+  //   }
+  //   return x;
+  // }
+  // ```
   static const CompileTimeErrorCode READ_POTENTIALLY_UNASSIGNED_FINAL =
       CompileTimeErrorCode(
     'READ_POTENTIALLY_UNASSIGNED_FINAL',
-    "The final variable '{0}' can't be read because it is potentially "
+    "The final variable '{0}' can't be read because it's potentially "
         "unassigned at this point.",
     correctionMessage:
         "Ensure that it is assigned on necessary execution paths.",
@@ -12362,9 +12845,44 @@
   );
 
   /**
-   * A factory constructor can't redirect to a non-generative constructor of an
-   * abstract class.
+   * Parameters:
+   * 0: the name of the redirecting constructor
+   * 1: the name of the abstract class defining the constructor being redirected to
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a constructor redirects to a
+  // constructor in an abstract class.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the factory
+  // constructor in `A` redirects to a constructor in `B`, but `B` is an
+  // abstract class:
+  //
+  // ```dart
+  // class A {
+  //   factory A() = [!B!];
+  // }
+  //
+  // abstract class B implements A {}
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the code redirects to the correct constructor, then change the class so
+  // that it isn't abstract:
+  //
+  // ```dart
+  // class A {
+  //   factory A() = B;
+  // }
+  //
+  // class B implements A {}
+  // ```
+  //
+  // Otherwise, change the factory constructor so that it either redirects to a
+  // constructor in a concrete class, or has a concrete implementation.
   static const CompileTimeErrorCode REDIRECT_TO_ABSTRACT_CLASS_CONSTRUCTOR =
       CompileTimeErrorCode(
     'REDIRECT_TO_ABSTRACT_CLASS_CONSTRUCTOR',
@@ -12517,9 +13035,57 @@
   );
 
   /**
-   * 7.6.2 Factories: It is a compile-time error if <i>k</i> is prefixed with
-   * the const modifier but <i>k'</i> is not a constant constructor.
+   * Parameters:
+   * 0: the name of the constructor
+   * 1: the name of the class containing the constructor
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when a constructor redirects to a
+  // constructor that doesn't exist.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the factory
+  // constructor in `A` redirects to a constructor in `B` that doesn't exist:
+  //
+  // ```dart
+  // class A {
+  //   factory A() = [!B.name!];
+  // }
+  //
+  // class B implements A {
+  //   B();
+  // }
+  // ```
+  //
+  // #### Common fixes
+  //
+  // If the constructor being redirected to is correct, then define the
+  // constructor:
+  //
+  // ```dart
+  // class A {
+  //   factory A() = B.name;
+  // }
+  //
+  // class B implements A {
+  //   B();
+  //   B.name();
+  // }
+  // ```
+  //
+  // If a different constructor should be invoked, then update the redirect:
+  //
+  // ```dart
+  // class A {
+  //   factory A() = B;
+  // }
+  //
+  // class B implements A {
+  //   B();
+  // }
+  // ```
   static const CompileTimeErrorCode REDIRECT_TO_MISSING_CONSTRUCTOR =
       CompileTimeErrorCode(
     'REDIRECT_TO_MISSING_CONSTRUCTOR',
@@ -13442,17 +14008,45 @@
   );
 
   /**
-   * It is an error if any case of a switch statement except the last case (the
-   * default case if present) may complete normally. The previous syntactic
-   * restriction requiring the last statement of each case to be one of an
-   * enumerated list of statements (break, continue, return, throw, or rethrow)
-   * is removed.
+   * No parameters.
    */
+  // #### Description
+  //
+  // The analyzer produces this diagnostic when the statements following a
+  // `case` label in a `switch` statement could fall through to the next `case`
+  // or `default` label.
+  //
+  // #### Example
+  //
+  // The following code produces this diagnostic because the `case` label with
+  //  a value of zero (`0`) falls through to the `default` statements:
+  //
+  // ```dart
+  // void f(int a) {
+  //   switch (a) {
+  //     [!case!] 0:
+  //       print(0);
+  //     default:
+  //       return;
+  //   }
+  // }
+  // ```
+  //
+  // #### Common fixes
+  //
+  // Change the flow of control so that the `case` won't fall through. There
+  // are several ways that this can be done, including adding one of the
+  // following at the end of the current list of statements:
+  // - a `return` statement,
+  // - a `throw` expression,
+  // - a `break` statement,
+  // - a `continue`, or
+  // - an invocation of a function or method whose return type is `Never`.
   static const CompileTimeErrorCode SWITCH_CASE_COMPLETES_NORMALLY =
       CompileTimeErrorCode(
     'SWITCH_CASE_COMPLETES_NORMALLY',
-    "The 'case' should not complete normally.",
-    correctionMessage: "Try adding 'break', or 'return', etc.",
+    "The 'case' shouldn't complete normally.",
+    correctionMessage: "Try adding 'break', 'return', or 'throw'.",
   );
 
   /**
diff --git a/pkg/analyzer/lib/src/test_utilities/mock_packages.dart b/pkg/analyzer/lib/src/test_utilities/mock_packages.dart
index 9c4b72b..5c68765 100644
--- a/pkg/analyzer/lib/src/test_utilities/mock_packages.dart
+++ b/pkg/analyzer/lib/src/test_utilities/mock_packages.dart
@@ -51,25 +51,62 @@
     libFolder.getChildAssumingFile('meta.dart').writeAsStringSync(r'''
 library meta;
 
-const _AlwaysThrows alwaysThrows = const _AlwaysThrows();
-const _DoNotStore doNotStore = _DoNotStore();
-const _Factory factory = const _Factory();
-const Immutable immutable = const Immutable();
-const _Internal internal = const Internal();
-const _Literal literal = const _Literal();
-const _MustCallSuper mustCallSuper = const _MustCallSuper();
-const _NonVirtual nonVirtual = const _NonVirtual();
-const _OptionalTypeArgs optionalTypeArgs = const _OptionalTypeArgs();
-const _Protected protected = const _Protected();
-const Required required = const Required();
-const _Sealed sealed = const _Sealed();
-const UseResult useResult = UseResult();
-const _VisibleForOverriding visibleForOverriding = _VisibleForOverriding();
-const _VisibleForTesting visibleForTesting = const _VisibleForTesting();
+import 'meta_meta.dart';
 
-class _AlwaysThrows {
-  const _AlwaysThrows();
+const _AlwaysThrows alwaysThrows = _AlwaysThrows();
+
+@Deprecated('Use the `covariant` modifier instead')
+const _Checked checked = _Checked();
+
+const _DoNotStore doNotStore = _DoNotStore();
+
+const _Experimental experimental = _Experimental();
+
+const _Factory factory = _Factory();
+
+const Immutable immutable = Immutable();
+
+const _Internal internal = _Internal();
+
+const _IsTest isTest = _IsTest();
+
+const _IsTestGroup isTestGroup = _IsTestGroup();
+
+const _Literal literal = _Literal();
+
+const _MustCallSuper mustCallSuper = _MustCallSuper();
+
+const _NonVirtual nonVirtual = _NonVirtual();
+
+const _OptionalTypeArgs optionalTypeArgs = _OptionalTypeArgs();
+
+const _Protected protected = _Protected();
+
+const Required required = Required();
+
+const _Sealed sealed = _Sealed();
+
+const UseResult useResult = UseResult();
+
+@Deprecated('No longer has meaning')
+const _Virtual virtual = _Virtual();
+
+const _VisibleForOverriding visibleForOverriding = _VisibleForOverriding();
+
+const _VisibleForTesting visibleForTesting = _VisibleForTesting();
+
+class Immutable {
+  final String reason;
+
+  const Immutable([this.reason = '']);
 }
+
+class Required {
+  final String reason;
+
+  const Required([this.reason = '']);
+}
+
 @Target({
   TargetKind.field,
   TargetKind.function,
@@ -77,50 +114,91 @@
   TargetKind.method,
   TargetKind.topLevelVariable,
 })
+class UseResult {
+  final String reason;
+
+  final String? parameterDefined;
+
+  const UseResult([this.reason = '']) : parameterDefined = null;
+
+  const UseResult.unless({required this.parameterDefined, this.reason = ''});
+}
+
+class _AlwaysThrows {
+  const _AlwaysThrows();
+}
+
+class _Checked {
+  const _Checked();
+}
+
+@Target({
+  TargetKind.classType,
+  TargetKind.function,
+  TargetKind.getter,
+  TargetKind.library,
+  TargetKind.method,
+})
 class _DoNotStore {
   const _DoNotStore();
 }
+
+class _Experimental {
+  const _Experimental();
+}
+
 class _Factory {
   const _Factory();
 }
-class Immutable {
-  final String reason;
-  const Immutable([this.reason]);
-}
+
 class _Internal {
-  const Internal();
+  const _Internal();
 }
+
+class _IsTest {
+  const _IsTest();
+}
+
+class _IsTestGroup {
+  const _IsTestGroup();
+}
+
 class _Literal {
   const _Literal();
 }
+
 class _MustCallSuper {
   const _MustCallSuper();
 }
+
 class _NonVirtual {
   const _NonVirtual();
 }
+
+@Target({
+  TargetKind.classType,
+  TargetKind.extension,
+  TargetKind.function,
+  TargetKind.method,
+  TargetKind.mixinType,
+  TargetKind.typedefType,
+})
 class _OptionalTypeArgs {
   const _OptionalTypeArgs();
 }
+
 class _Protected {
   const _Protected();
 }
-class Required {
-  final String reason;
-  const Required([this.reason]);
-}
+
 class _Sealed {
   const _Sealed();
 }
-class UseResult {
-  final String? parameterDefined;
-  final String reason;
-  const UseResult([this.reason = '']);
-  const UseResult.unless({required this.parameterDefined, this.reason = ''});
-}
+
 class _VisibleForOverriding {
   const _VisibleForOverriding();
 }
+
 class _VisibleForTesting {
   const _VisibleForTesting();
 }
@@ -128,10 +206,12 @@
     libFolder.getChildAssumingFile('meta_meta.dart').writeAsStringSync(r'''
 library meta_meta;
 
+@Target({TargetKind.classType})
 class Target {
   final Set<TargetKind> kinds;
   const Target(this.kinds);
 }
+
 enum TargetKind {
   classType,
   enumType,
diff --git a/pkg/analyzer/lib/src/test_utilities/mock_sdk.dart b/pkg/analyzer/lib/src/test_utilities/mock_sdk.dart
index 84784c3..d1cb139 100644
--- a/pkg/analyzer/lib/src/test_utilities/mock_sdk.dart
+++ b/pkg/analyzer/lib/src/test_utilities/mock_sdk.dart
@@ -624,6 +624,8 @@
 
 class Type {}
 
+class TypeError extends Error {}
+
 class UnsupportedError {
   UnsupportedError(String message);
 }
diff --git a/pkg/analyzer/messages.yaml b/pkg/analyzer/messages.yaml
index 8c6aa4a..1919dae 100644
--- a/pkg/analyzer/messages.yaml
+++ b/pkg/analyzer/messages.yaml
@@ -2780,7 +2780,31 @@
       Parameters:
       0: the name of the type
   CONTINUE_LABEL_ON_SWITCH:
-    problemMessage: A continue label resolves to switch, must be loop or switch member
+    problemMessage: A `continue` label resolves to a `switch` statement, but the label must be on a loop or a switch member.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when the label in a `continue`
+      statement resolves to a label on a `switch` statement.
+
+      #### Example
+
+      The following code produces this diagnostic because the label `l`, used to
+      label a `switch` statement, is used in the `continue` statement:
+
+      ```dart
+      void f(int i) {
+        l: switch (i) {
+          case 0:
+            continue [!l!];
+        }
+      }
+      ```
+
+      #### Common fixes
+
+      Find a different way to achieve the control flow you need; for example, by
+      introducing a loop that re-executes the `switch` statement.
   COULD_NOT_INFER:
     problemMessage: "Couldn't infer type parameter '{0}'.{1}"
     comment: |-
@@ -3095,9 +3119,44 @@
       }
       ```
   DISALLOWED_TYPE_INSTANTIATION_EXPRESSION:
-    problemMessage: Only a generic type, generic function, generic instance method, or generic constructor can be type instantiated.
-    correctionMessage: Try instantiating the type(s) of a generic type, generic function, generic instance method, or generic constructor.
+    problemMessage: Only a generic type, generic function, generic instance method, or generic constructor can have type arguments.
+    correctionMessage: Try removing the type arguments, or instantiating the type(s) of a generic type, generic function, generic instance method, or generic constructor.
     comment: No parameters.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when an expression with a value that
+      is anything other than one of the allowed kinds of values is followed by
+      type arguments. The allowed kinds of values are:
+      - generic types,
+      - generic constructors, and
+      - generic functions, including top-level functions, static and instance
+        members, and local functions.
+
+      #### Example
+
+      The following code produces this diagnostic because `i` is a top-level
+      variable, which isn't one of the allowed cases:
+
+      ```dart
+      int i = 1;
+
+      void f() {
+        print([!i!]<int>);
+      }
+      ```
+
+      #### Common fixes
+
+      If the referenced value is correct, then remove the type arguments:
+
+      ```dart
+      int i = 1;
+
+      void f() {
+        print(i);
+      }
+      ```
   DUPLICATE_CONSTRUCTOR_NAME:
     sharedName: DUPLICATE_CONSTRUCTOR
     problemMessage: "The constructor with name '{0}' is already defined."
@@ -3354,6 +3413,40 @@
   ENUM_CONSTANT_SAME_NAME_AS_ENCLOSING:
     problemMessage: "The name of the enum constant can't be the same as the enum's name."
     correctionMessage: Try renaming the constant.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when an enum constant 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`:
+
+      ```dart
+      enum E {
+        [!E!]
+      }
+      ```
+
+      #### Common fixes
+
+      If the name of the enum is correct, then rename the constant:
+
+      ```dart
+      enum E {
+        e
+      }
+      ```
+
+      If the name of the constant is correct, then rename the enum:
+
+      ```dart
+      enum F {
+        E
+      }
+      ```
   ENUM_CONSTANT_WITH_NON_CONST_CONSTRUCTOR:
     problemMessage: The invoked constructor isn't a const constructor.
     correctionMessage: Try invoking a const generative constructor.
@@ -4016,6 +4109,50 @@
     sharedName: EXTERNAL_WITH_INITIALIZER
     problemMessage: External fields can't have initializers.
     correctionMessage: "Try removing the field initializer or the 'external' keyword from the field declaration."
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a field or variable marked with
+      the keyword `external` has an initializer, or when an external field is
+      initialized in a constructor.
+
+      #### Examples
+
+      The following code produces this diagnostic because the external field `x`
+      is assigned a value in an initializer:
+
+      ```dart
+      class C {
+        external int x;
+        C() : [!x!] = 0;
+      }
+      ```
+
+      The following code produces this diagnostic because the external field `x`
+      has an initializer:
+
+      ```dart
+      class C {
+        external final int [!x!] = 0;
+      }
+      ```
+
+      The following code produces this diagnostic because the external top level
+      variable `x` has an initializer:
+
+      ```dart
+      external final int [!x!] = 0;
+      ```
+
+      #### Common fixes
+
+      Remove the initializer:
+
+      ```dart
+      class C {
+        external final int x;
+      }
+      ```
   EXTERNAL_FIELD_INITIALIZER:
     sharedName: EXTERNAL_WITH_INITIALIZER
     problemMessage: External fields can't have initializers.
@@ -4355,9 +4492,41 @@
     problemMessage: Initializing formal parameters can only be used in constructors.
     correctionMessage: Try using a normal parameter.
     comment: |-
-      7.6.1 Generative Constructors: It is a compile-time error if an
-      initializing formal is used by a function other than a non-redirecting
-      generative constructor.
+      No parameters.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when an initializing formal
+      parameter is used in the parameter list for anything other than a
+      constructor.
+
+      #### Example
+
+      The following code produces this diagnostic because the initializing
+      formal parameter `this.x` is being used in the method `m`:
+
+      ```dart
+      class A {
+        int x = 0;
+
+        m([[!this.x!] = 0]) {}
+      }
+      ```
+
+      #### Common fixes
+
+      Replace the initializing formal parameter with a normal parameter and
+      assign the field within the body of the method:
+
+      ```dart
+      class A {
+        int x = 0;
+
+        m([int x = 0]) {
+          this.x = x;
+        }
+      }
+      ```
   FIELD_INITIALIZER_REDIRECTING_CONSTRUCTOR:
     problemMessage: "The redirecting constructor can't have a field initializer."
     correctionMessage: Try initializing the field in the constructor being redirected to.
@@ -5296,11 +5465,40 @@
     problemMessage: "The imported library '{0}' can't have a part-of directive."
     correctionMessage: Try importing the library that the part is a part of.
     comment: |-
-      14.1 Imports: It is a compile-time error if the specified URI of an
-      immediate import does not refer to a library declaration.
-
       Parameters:
       0: the uri pointing to a non-library declaration
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a [part file][] is imported
+      into a library.
+
+      #### Example
+
+      Given a [part file][] named `part.dart` containing the following:
+
+      ```dart
+      %uri="lib/part.dart"
+      part of lib;
+
+      class C{}
+      ```
+
+      The following code produces this diagnostic because imported files can't
+      have a part-of directive:
+
+      ```dart
+      library lib;
+
+      import [!'part.dart'!];
+
+      C c = C();
+      ```
+
+      #### Common fixes
+
+      Import the library that contains the [part file][] rather than the
+      [part file][] itself.
   INCONSISTENT_CASE_EXPRESSION_TYPES:
     problemMessage: "Case expressions must have the same types, '{0}' isn't a '{1}'."
     comment: |-
@@ -5382,12 +5580,45 @@
   INCONSISTENT_LANGUAGE_VERSION_OVERRIDE:
     problemMessage: Parts must have exactly the same language version override as the library.
     comment: |-
-      It is a compile-time error if a part file has a different language version
-      override than its library.
+      No parameters.
+    documentation: |-
+      #### Description
 
-      https://github.com/dart-lang/language/blob/master/accepted/
-      future-releases/language-versioning/feature-specification.md
-      #individual-library-language-version-override
+      The analyzer produces this diagnostic when a [part file][] has a language
+      version override comment that specifies a different language version than
+      the one being used for the library to which the part belongs.
+
+      #### Example
+
+      Given a [part file][] named `part.dart` that contains the following:
+
+      ```dart
+      %uri="lib/part.dart"
+      // @dart = 2.6
+      part of 'test.dart';
+      ```
+
+      The following code produces this diagnostic because the parts of a library
+      must have the same language version as the defining compilation unit:
+
+      ```dart
+      // @dart = 2.5
+      part [!'part.dart'!];
+      ```
+
+      #### Common fixes
+
+      Remove the language version override from the [part file][], so that it
+      implicitly uses the same version as the defining compilation unit:
+
+      ```dart
+      part of 'test.dart';
+      ```
+
+      If necessary, either adjust the language version override in the defining
+      compilation unit to be appropriate for the code in the part, or migrate
+      the code in the [part file][] to be consistent with the new language
+      version.
   INITIALIZER_FOR_NON_EXISTENT_FIELD:
     problemMessage: "'{0}' isn't a field in the enclosing class."
     correctionMessage: "Try correcting the name to match an existing field, or defining a field named '{0}'."
@@ -7946,11 +8177,40 @@
       9.1 Mixin Application: It is a compile-time error if <i>S</i> does not
       denote a class available in the immediately enclosing scope.
   MULTIPLE_REDIRECTING_CONSTRUCTOR_INVOCATIONS:
-    problemMessage: "Constructors can have at most one 'this' redirection."
+    problemMessage: Constructors can have only one 'this' redirection, at most.
     correctionMessage: Try removing all but one of the redirections.
     comment: |-
-      7.6.1 Generative Constructors: A generative constructor may be redirecting,
-      in which case its only action is to invoke another generative constructor.
+      No parameters.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a constructor redirects to more
+      than one other constructor in the same class (using `this`).
+
+      #### Example
+
+      The following code produces this diagnostic because the unnamed
+      constructor in `C` is redirecting to both `this.a` and `this.b`:
+
+      ```dart
+      class C {
+        C() : this.a(), [!this.b()!];
+        C.a();
+        C.b();
+      }
+      ```
+
+      #### Common fixes
+
+      Remove all but one of the redirections:
+
+      ```dart
+      class C {
+        C() : this.a();
+        C.a();
+        C.b();
+      }
+      ```
   MULTIPLE_SUPER_INITIALIZERS:
     problemMessage: "A constructor can have at most one 'super' initializer."
     correctionMessage: "Try removing all but one of the 'super' initializers."
@@ -8855,14 +9115,75 @@
     problemMessage: "The unnamed constructor of superclass '{0}' (called by the default constructor of '{1}') must be a generative constructor, but factory found."
     correctionMessage: "Try adding an explicit constructor that has a different superinitializer or changing the superclass constructor '{2}' to not be a factory constructor."
     comment: |-
-      An error code for when a class has no explicit constructor, and therefore
-      a constructor is implicitly defined which uses a factory as a
-      superinitializer. See [NON_GENERATIVE_CONSTRUCTOR].
-
       Parameters:
       0: the name of the superclass
       1: the name of the current class
       2: the implicitly called factory constructor of the superclass
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a class has an implicit
+      generative constructor and the superclass has an explicit unnamed factory
+      constructor. The implicit constructor in the subclass implicitly invokes
+      the unnamed constructor in the superclass, but generative constructors can
+      only invoke another generative constructor, not a factory constructor.
+
+      #### Example
+
+      The following code produces this diagnostic because the implicit
+      constructor in `B` invokes the unnamed constructor in `A`, but the
+      constructor in `A` is a factory constructor, when a generative constructor
+      is required:
+
+      ```dart
+      class A {
+        factory A() => throw 0;
+        A.named();
+      }
+
+      class [!B!] extends A {}
+      ```
+
+      #### Common fixes
+
+      If the unnamed constructor in the superclass can be a generative
+      constructor, then change it to be a generative constructor:
+
+      ```dart
+      class A {
+        A();
+        A.named();
+      }
+
+      class B extends A { }
+      ```
+
+      If the unnamed constructor can't be a generative constructor and there are
+      other generative constructors in the superclass, then explicitly invoke
+      one of them:
+
+      ```dart
+      class A {
+        factory A() => throw 0;
+        A.named();
+      }
+
+      class B extends A {
+        B() : super.named();
+      }
+      ```
+
+      If there are no generative constructors that can be used and none can be
+      added, then implement the superclass rather than extending it:
+
+      ```dart
+      class A {
+        factory A() => throw 0;
+        A.named();
+      }
+
+      class B implements A {}
+      ```
   NON_SYNC_FACTORY:
     problemMessage: "Factory bodies can't use 'async', 'async*', or 'sync*'."
     hasPublishedDocs: true
@@ -9584,16 +9905,72 @@
          constructor
       1: the name of the subclass that does not contain any explicit constructors
   NO_GENERATIVE_CONSTRUCTORS_IN_SUPERCLASS:
-    problemMessage: "The class '{0}' cannot extend '{1}' because '{1}' only has factory constructors (no generative constructors), and '{0}' has at least one generative constructor."
-    correctionMessage: "Try implementing the class instead, adding a generative (not factory) constructor to the superclass {0}, or a factory constructor to the subclass."
+    problemMessage: "The class '{0}' can't extend '{1}' because '{1}' only has factory constructors (no generative constructors), and '{0}' has at least one generative constructor."
+    correctionMessage: "Try implementing the class instead, adding a generative (not factory) constructor to the superclass '{1}', or a factory constructor to the subclass."
     comment: |-
-      User friendly specialized error for [NON_GENERATIVE_CONSTRUCTOR]. This
-      handles the case of `class E extends Exception` which will never work
-      because [Exception] has no generative constructors.
-
       Parameters:
       0: the name of the subclass
       1: the name of the superclass
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a class that has at least one
+      generative constructor (whether explicit or implicit) has a superclass
+      that doesn't have any generative constructors. Every generative
+      constructor, except the one defined in `Object`, invokes, either
+      explicitly or implicitly, one of the generative constructors from its
+      superclass.
+
+      #### Example
+
+      The following code produces this diagnostic because the class `B` has an
+      implicit generative constructor that can't invoke a generative constructor
+      from `A` because `A` doesn't have any generative constructors:
+
+      ```dart
+      class A {
+        factory A.none() => throw '';
+      }
+
+      class B extends [!A!] {}
+      ```
+
+      #### Common fixes
+
+      If the superclass should have a generative constructor, then add one:
+
+      ```dart
+      class A {
+        A();
+        factory A.none() => throw '';
+      }
+
+      class B extends A {}
+      ```
+
+      If the subclass shouldn't have a generative constructor, then remove it by
+      adding a factory constructor:
+
+      ```dart
+      class A {
+        factory A.none() => throw '';
+      }
+
+      class B extends A {
+        factory B.none() => throw '';
+      }
+      ```
+
+      If the subclass must have a generative constructor but the superclass
+      can't have one, then implement the superclass instead:
+
+      ```dart
+      class A {
+        factory A.none() => throw '';
+      }
+
+      class B implements A {}
+      ```
   NULLABLE_TYPE_IN_EXTENDS_CLAUSE:
     problemMessage: "A class can't extend a nullable type."
     correctionMessage: Try removing the question mark.
@@ -9863,8 +10240,8 @@
       If the library should be using a different file as a part, then change the
       URI in the part directive to be the URI of the other file.
 
-      If the part file should be a part of this library, then update the URI (or
-      library name) in the part-of directive to be the URI (or name) of the
+      If the [part file][] should be a part of this library, then update the URI
+      (orlibrary name) in the part-of directive to be the URI (or name) of the
       correct library.
   PART_OF_NON_PART:
     problemMessage: "The included part '{0}' must have a part-of directive."
@@ -9924,13 +10301,14 @@
       #### Description
 
       The analyzer produces this diagnostic when a library that doesn't have a
-      `library` directive (and hence has no name) contains a `part` directive and
-      the `part of` directive in the part file uses a name to specify the library
-      that it's a part of.
+      `library` directive (and hence has no name) contains a `part` directive
+      and the `part of` directive in the [part file][] uses a name to specify
+      the library that it's a part of.
 
       #### Example
 
-      Given a part file named `part_file.dart` containing the following code:
+      Given a [part file][] named `part_file.dart` containing the following
+      code:
 
       ```dart
       %uri="lib/part_file.dart"
@@ -9938,8 +10316,8 @@
       ```
 
       The following code produces this diagnostic because the library including
-      the part file doesn't have a name even though the part file uses a name to
-      specify which library it's a part of:
+      the [part file][] doesn't have a name even though the [part file][] uses a
+      name to specify which library it's a part of:
 
       ```dart
       part [!'part_file.dart'!];
@@ -9947,8 +10325,8 @@
 
       #### Common fixes
 
-      Change the `part of` directive in the part file to specify its library by
-      URI:
+      Change the `part of` directive in the [part file][] to specify its library
+      by URI:
 
       ```dart
       part of 'test.dart';
@@ -10043,17 +10421,56 @@
 
       If the name is wrong, then correct the name.
   PREFIX_SHADOWED_BY_LOCAL_DECLARATION:
-    problemMessage: "The prefix '{0}' can't be used here because it is shadowed by a local declaration."
+    problemMessage: "The prefix '{0}' can't be used here because it's shadowed by a local declaration."
     correctionMessage: Try renaming either the prefix or the local declaration.
     comment: |-
-      From the `Static Types` section of the spec:
+      Parameters:
+      0: the prefix being shadowed
+    documentation: |-
+      #### Description
 
-          A type T is malformed if:
-          - T has the form id or the form prefix.id, and in the enclosing lexical
-            scope, the name id (respectively prefix.id) does not denote a type.
+      The analyzer produces this diagnostic when an import prefix is used in a
+      context where it isn't visible because it was shadowed by a local
+      declaration.
 
-      In particular, this means that if an import prefix is shadowed by a local
-      declaration, it is an error to try to use it as a prefix for a type name.
+      #### Example
+
+      The following code produces this diagnostic because the prefix `a` is
+      being used to access the class `Future`, but isn't visible because it's
+      shadowed by the parameter `a`:
+
+      ```dart
+      import 'dart:async' as a;
+
+      a.Future? f(int a) {
+        [!a!].Future? x;
+        return x;
+      }
+      ```
+
+      #### Common fixes
+
+      Rename either the prefix:
+
+      ```dart
+      import 'dart:async' as p;
+
+      p.Future? f(int a) {
+        p.Future? x;
+        return x;
+      }
+      ```
+
+      Or rename the local variable:
+
+      ```dart
+      import 'dart:async' as a;
+
+      a.Future? f(int p) {
+        a.Future? x;
+        return x;
+      }
+      ```
   PRIVATE_COLLISION_IN_MIXIN_APPLICATION:
     problemMessage: "The private name '{0}', defined by '{1}', conflicts with the same name defined by '{2}'."
     correctionMessage: "Try removing '{1}' from the 'with' clause."
@@ -10138,11 +10555,88 @@
       }
       ```
   PRIVATE_SETTER:
-    problemMessage: "The setter '{0}' is private and can't be accessed outside of the library that declares it."
+    problemMessage: "The setter '{0}' is private and can't be accessed outside the library that declares it."
     correctionMessage: Try making it public.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a private setter is used in a
+      library where it isn't visible.
+
+      #### Example
+
+      Given a file named `a.dart` that contains the following:
+
+      ```dart
+      %uri="lib/a.dart"
+      class A {
+        static int _f = 0;
+      }
+      ```
+
+      The following code produces this diagnostic because it references the
+      private setter `_f` even though the setter isn't visible:
+
+      ```dart
+      import 'a.dart';
+
+      void f() {
+        A.[!_f!] = 0;
+      }
+      ```
+
+      #### Common fixes
+
+      If you're able to make the setter public, then do so:
+
+      ```dart
+      %uri="lib/a.dart"
+      class A {
+        static int f = 0;
+      }
+      ```
+
+      If you aren't able to make the setter public, then find a different way to
+      implement the code.
   READ_POTENTIALLY_UNASSIGNED_FINAL:
-    problemMessage: "The final variable '{0}' can't be read because it is potentially unassigned at this point."
+    problemMessage: "The final variable '{0}' can't be read because it's potentially unassigned at this point."
     correctionMessage: Ensure that it is assigned on necessary execution paths.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a final local variable that
+      isn't initialized at the declaration site is read at a point where the
+      compiler can't prove that the variable is always initialized before it's
+      referenced.
+
+      #### Example
+
+      The following code produces this diagnostic because the final local
+      variable `x` is read (on line 3) when it's possible that it hasn't yet
+      been initialized:
+
+      ```dart
+      int f() {
+        final int x;
+        return [!x!];
+      }
+      ```
+
+      #### Common fixes
+
+      Ensure that the variable has been initialized before it's read:
+
+      ```dart
+      int f(bool b) {
+        final int x;
+        if (b) {
+          x = 0;
+        } else {
+          x = 1;
+        }
+        return x;
+      }
+      ```
   RECURSIVE_COMPILE_TIME_CONSTANT:
     problemMessage: The compile-time constant expression depends on itself.
     hasPublishedDocs: true
@@ -10446,8 +10940,44 @@
     problemMessage: "The redirecting constructor '{0}' can't redirect to a constructor of the abstract class '{1}'."
     correctionMessage: Try redirecting to a constructor of a different class.
     comment: |-
-      A factory constructor can't redirect to a non-generative constructor of an
-      abstract class.
+      Parameters:
+      0: the name of the redirecting constructor
+      1: the name of the abstract class defining the constructor being redirected to
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a constructor redirects to a
+      constructor in an abstract class.
+
+      #### Example
+
+      The following code produces this diagnostic because the factory
+      constructor in `A` redirects to a constructor in `B`, but `B` is an
+      abstract class:
+
+      ```dart
+      class A {
+        factory A() = [!B!];
+      }
+
+      abstract class B implements A {}
+      ```
+
+      #### Common fixes
+
+      If the code redirects to the correct constructor, then change the class so
+      that it isn't abstract:
+
+      ```dart
+      class A {
+        factory A() = B;
+      }
+
+      class B implements A {}
+      ```
+
+      Otherwise, change the factory constructor so that it either redirects to a
+      constructor in a concrete class, or has a concrete implementation.
   REDIRECT_TO_INVALID_FUNCTION_TYPE:
     problemMessage: "The redirected constructor '{0}' has incompatible parameters with '{1}'."
     correctionMessage: Try redirecting to a different constructor.
@@ -10586,8 +11116,57 @@
     problemMessage: "The constructor '{0}' couldn't be found in '{1}'."
     correctionMessage: "Try redirecting to a different constructor, or define the constructor named '{0}'."
     comment: |-
-      7.6.2 Factories: It is a compile-time error if <i>k</i> is prefixed with
-      the const modifier but <i>k'</i> is not a constant constructor.
+      Parameters:
+      0: the name of the constructor
+      1: the name of the class containing the constructor
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a constructor redirects to a
+      constructor that doesn't exist.
+
+      #### Example
+
+      The following code produces this diagnostic because the factory
+      constructor in `A` redirects to a constructor in `B` that doesn't exist:
+
+      ```dart
+      class A {
+        factory A() = [!B.name!];
+      }
+
+      class B implements A {
+        B();
+      }
+      ```
+
+      #### Common fixes
+
+      If the constructor being redirected to is correct, then define the
+      constructor:
+
+      ```dart
+      class A {
+        factory A() = B.name;
+      }
+
+      class B implements A {
+        B();
+        B.name();
+      }
+      ```
+
+      If a different constructor should be invoked, then update the redirect:
+
+      ```dart
+      class A {
+        factory A() = B;
+      }
+
+      class B implements A {
+        B();
+      }
+      ```
   REDIRECT_TO_NON_CLASS:
     problemMessage: "The name '{0}' isn't a type and can't be used in a redirected constructor."
     correctionMessage: Try redirecting to a different constructor.
@@ -11539,14 +12118,43 @@
       }
       ```
   SWITCH_CASE_COMPLETES_NORMALLY:
-    problemMessage: "The 'case' should not complete normally."
-    correctionMessage: "Try adding 'break', or 'return', etc."
+    problemMessage: "The 'case' shouldn't complete normally."
+    correctionMessage: "Try adding 'break', 'return', or 'throw'."
     comment: |-
-      It is an error if any case of a switch statement except the last case (the
-      default case if present) may complete normally. The previous syntactic
-      restriction requiring the last statement of each case to be one of an
-      enumerated list of statements (break, continue, return, throw, or rethrow)
-      is removed.
+      No parameters.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when the statements following a
+      `case` label in a `switch` statement could fall through to the next `case`
+      or `default` label.
+
+      #### Example
+
+      The following code produces this diagnostic because the `case` label with
+       a value of zero (`0`) falls through to the `default` statements:
+
+      ```dart
+      void f(int a) {
+        switch (a) {
+          [!case!] 0:
+            print(0);
+          default:
+            return;
+        }
+      }
+      ```
+
+      #### Common fixes
+
+      Change the flow of control so that the `case` won't fall through. There
+      are several ways that this can be done, including adding one of the
+      following at the end of the current list of statements:
+      - a `return` statement,
+      - a `throw` expression,
+      - a `break` statement,
+      - a `continue`, or
+      - an invocation of a function or method whose return type is `Never`.
   SWITCH_EXPRESSION_NOT_ASSIGNABLE:
     problemMessage: "Type '{0}' of the switch expression isn't assignable to the type '{1}' of case expressions."
     hasPublishedDocs: true
@@ -15511,6 +16119,32 @@
     problemMessage: "'{0}' is marked 'doNotStore' and shouldn't be assigned to a field or top-level variable."
     correctionMessage: Try removing the assignment.
     comment: Users should not assign values marked `@doNotStore`.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when the value of a function
+      (including methods and getters) that is explicitly or implicitly marked by
+      the `[doNotStore][meta-doNotStore]` annotation is stored in either a field
+      or top-level variable.
+
+      #### Example
+
+      The following code produces this diagnostic because the value of the
+      function `f` is being stored in the top-level variable `x`:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      @doNotStore
+      int f() => 1;
+
+      var x = [!f()!];
+      ```
+
+      #### Common fixes
+
+      Replace references to the field or variable with invocations of the
+      function producing the value.
   BODY_MIGHT_COMPLETE_NORMALLY_NULLABLE:
     problemMessage: "This function has a nullable return type of '{0}', but ends without returning a value."
     correctionMessage: "Try adding a return statement, or if no value is ever returned, try changing the return type to 'void'."
@@ -15518,6 +16152,40 @@
     comment: |-
       Parameters:
       0: the name of the declared return type
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a method or function can
+      implicitly return `null` by falling off the end. While this is valid Dart
+      code, it's better for the return of `null` to be explicit.
+
+      #### Example
+
+      The following code produces this diagnostic because the function `f`
+      implicitly returns `null`:
+
+      ```dart
+      String? [!f!]() {}
+      ```
+
+      #### Common fixes
+
+      If the return of `null` is intentional, then make it explicit:
+
+      ```dart
+      String? f() {
+        return null;
+      }
+      ```
+
+      If the function should return a non-null value along that path, then add
+      the missing return statement:
+
+      ```dart
+      String? f() {
+        return '';
+      }
+      ```
   CAN_BE_NULL_AFTER_NULL_AWARE:
     problemMessage: "The receiver uses '?.', so its value can be null."
     correctionMessage: "Replace the '.' with a '?.' in the invocation."
@@ -15775,6 +16443,55 @@
     problemMessage: "Using the 'new' keyword in a comment reference is deprecated."
     correctionMessage: Try referring to a constructor by its name.
     comment: No parameters.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a comment reference (the name
+      of a declaration enclosed in square brackets in a documentation comment)
+      uses the keyword `new` to refer to a constructor. This form is deprecated.
+
+      #### Examples
+
+      The following code produces this diagnostic because the unnamed
+      constructor is being referenced using `new C`:
+
+      ```dart
+      /// See [[!new!] C].
+      class C {
+        C();
+      }
+      ```
+
+      The following code produces this diagnostic because the constructor named
+      `c` is being referenced using `new C.c`:
+
+      ```dart
+      /// See [[!new!] C.c].
+      class C {
+        C.c();
+      }
+      ```
+
+      #### Common fixes
+
+      If you're referencing a named constructor, then remove the keyword `new`:
+
+      ```dart
+      /// See [C.c].
+      class C {
+        C.c();
+      }
+      ```
+
+      If you're referencing the unnamed constructor, then remove the keyword
+      `new` and append `.new` after the class name:
+
+      ```dart
+      /// See [C.new].
+      class C {
+        C.c();
+      }
+      ```
   DEPRECATED_MIXIN_FUNCTION:
     sharedName: DEPRECATED_SUBTYPE_OF_FUNCTION
     problemMessage: "Mixing in 'Function' is deprecated."
@@ -16173,11 +16890,49 @@
       ```
 
       If type arguments shouldn't be required for the class, then mark the class
-      with the `@optionalTypeArgs` annotation (from `package:meta`):
+      with the `[optionalTypeArgs][meta-optionalTypeArgs]` annotation (from
+      `package:meta`):
   IMPORT_OF_LEGACY_LIBRARY_INTO_NULL_SAFE:
-    problemMessage: "The library '{0}' is legacy, and should not be imported into a null safe library."
+    problemMessage: "The library '{0}' is legacy, and shouldn't be imported into a null safe library."
     correctionMessage: Try migrating the imported library.
-    comment: "https://github.com/dart-lang/sdk/issues/44063"
+    comment: |-
+      No parameters.
+
+      https://github.com/dart-lang/sdk/issues/44063
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a library that is null safe
+      imports a library that isn't null safe.
+
+      #### Example
+
+      Given a file named `a.dart` that contains the following:
+
+      ```dart
+      %uri="lib/a.dart"
+      // @dart = 2.9
+
+      class A {}
+      ```
+
+      The following code produces this diagnostic because a library that null
+      safe is importing a library that isn't null safe:
+
+      ```dart
+      import [!'a.dart'!];
+
+      A? f() => null;
+      ```
+
+      #### Common fixes
+
+      If you can migrate the imported library to be null safe, then migrate it
+      and update or remove the migrated library's language version.
+
+      If you can't migrate the imported library, then the importing library
+      needs to have a language version that is before 2.12, when null safety was
+      enabled by default.
   INFERENCE_FAILURE_ON_COLLECTION_LITERAL:
     problemMessage: "The type argument(s) of '{0}' can't be inferred."
     correctionMessage: "Use explicit type argument(s) for '{0}'."
@@ -16225,29 +16980,118 @@
       When "strict-inference" in enabled, function parameters must be
       declared with a specific type, or inherit a type.
   INVALID_ANNOTATION_TARGET:
-    problemMessage: "The annotation '{0}' can only be used on {1}"
+    problemMessage: "The annotation '{0}' can only be used on {1}."
     comment: |-
       Parameters:
       0: the name of the annotation
       1: the list of valid targets
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when an annotation is applied to a
+      kind of declaration that it doesn't support.
+
+      #### Example
+
+      The following code produces this diagnostic because the `optionalTypeArgs`
+      annotation isn't defined to be valid for top-level variables:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      @[!optionalTypeArgs!]
+      int x = 0;
+      ```
+
+      #### Common fixes
+
+      Remove the annotation from the declaration.
   INVALID_EXPORT_OF_INTERNAL_ELEMENT:
     problemMessage: "The member '{0}' can't be exported as a part of a package's public API."
     correctionMessage: "Try using a hide clause to hide '{0}'."
     comment: |-
-      This hint is generated anywhere where an element annotated with `@internal`
-      is exported as a part of a package's public API.
-
       Parameters:
       0: the name of the element
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a [public library][] exports a
+      declaration that is marked with the `[internal][meta-internal]`
+      annotation.
+
+      #### Example
+
+      Given a file named `a.dart` in the `src` directory that contains:
+
+      ```dart
+      %uri="lib/src/a.dart"
+      import 'package:meta/meta.dart';
+
+      @internal class One {}
+      ```
+
+      The following code, when found in a [public library][] produces this
+      diagnostic because the `export` directive is exporting a name that is only
+      intended to be used internally:
+
+      ```dart
+      [!export 'src/a.dart';!]
+      ```
+
+      #### Common fixes
+
+      If the export is needed, then add a `hide` clause to hide the internal
+      names:
+
+      ```dart
+      export 'src/a.dart' hide One;
+      ```
+
+      If the export isn't needed, then remove it.
   INVALID_EXPORT_OF_INTERNAL_ELEMENT_INDIRECTLY:
     problemMessage: "The member '{0}' can't be exported as a part of a package's public API, but is indirectly exported as part of the signature of '{1}'."
     correctionMessage: "Try using a hide clause to hide '{0}'."
     comment: |-
-      This hint is generated anywhere where an element annotated with `@internal`
-      is exported indirectly as a part of a package's public API.
-
       Parameters:
       0: the name of the element
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a [public library][] exports a
+      top-level function  with a return type or at least one parameter type that
+      is marked with the `[internal][meta-internal]` annotation.
+
+      #### Example
+
+      Given a file named `a.dart` in the `src` directory that contains the
+      following:
+
+      ```dart
+      %uri="lib/src/a.dart"
+      import 'package:meta/meta.dart';
+
+      @internal
+      typedef IntFunction = int Function();
+
+      int f(IntFunction g) => g();
+      ```
+
+      The following code produces this diagnostic because the function `f` has a
+      parameter of type `IntFunction`, and `IntFunction` is only intended to be
+      used internally:
+
+      ```dart
+      [!export 'src/a.dart' show f;!]
+      ```
+
+      #### Common fixes
+
+      If the function must be public, then make all the types in the function's
+      signature public types.
+
+      If the function doesn't need to be exported, then stop exporting it,
+      either by removing it from the `show` clause, adding it to the `hide`
+      clause, or by removing the export.
   INVALID_FACTORY_ANNOTATION:
     problemMessage: Only methods can be annotated as factories.
     comment: |-
@@ -16256,17 +17100,89 @@
   INVALID_FACTORY_METHOD_DECL:
     problemMessage: "Factory method '{0}' must have a return type."
     comment: |-
-      This hint is generated anywhere a @factory annotation is associated with
-      a method that does not declare a return type.
+      Parameters:
+      0: The name of the method
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a method that is annotated with
+      the `[factory][meta-factory]` annotation has a return type of `void`.
+
+      #### Example
+
+      The following code produces this diagnostic because the method `createC`
+      is annotated with the `[factory][meta-factory]` annotation but doesn't
+      return any value:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      class Factory {
+        @factory
+        void [!createC!]() {}
+      }
+
+      class C {}
+      ```
+
+      #### Common fixes
+
+      Change the return type to something other than `void`:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      class Factory {
+        @factory
+        C createC() => C();
+      }
+
+      class C {}
+      ```
   INVALID_FACTORY_METHOD_IMPL:
     problemMessage: "Factory method '{0}' doesn't return a newly allocated object."
     comment: |-
-      This hint is generated anywhere a @factory annotation is associated with
-      a non-abstract method that can return anything other than a newly allocated
-      object.
-
       Parameters:
       0: the name of the method
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a method that is annotated with
+      the `[factory][meta-factory]` annotation doesn't return a newly allocated
+      object.
+
+      #### Example
+
+      The following code produces this diagnostic because the method `createC`
+      returns the value of a field rather than a newly created instance of `C`:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      class Factory {
+        C c = C();
+
+        @factory
+        C [!createC!]() => c;
+      }
+
+      class C {}
+      ```
+
+      #### Common fixes
+
+      Change the method to return a newly created instance of the return type:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      class Factory {
+        @factory
+        C createC() => C();
+      }
+
+      class C {}
+      ```
   INVALID_IMMUTABLE_ANNOTATION:
     problemMessage: Only classes can be annotated as being immutable.
     comment: |-
@@ -16275,121 +17191,135 @@
   INVALID_INTERNAL_ANNOTATION:
     problemMessage: "Only public elements in a package's private API can be annotated as being internal."
     comment: |-
-      This hint is generated anywhere a @internal annotation is associated with
-      an element found in a package's public API.
+      No parameters.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a declaration is annotated with
+      the `[internal][meta-internal]` annotation and that declaration is either
+      in a [public library][] or has a private name.
+
+      #### Example
+
+      The following code, when in a [public library][], produces this diagnostic
+      because the `[internal][meta-internal]` annotation can't be applied to
+      declarations in a [public library][]:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      [!@internal!]
+      class C {}
+      ```
+
+      The following code, whether in a public or internal library, produces this
+      diagnostic because the `[internal][meta-internal]` annotation can't be
+      applied to declarations with private names:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      [!@internal!]
+      class _C {}
+      
+      void f(_C c) {}
+      ```
+
+      #### Common fixes
+
+      If the declaration has a private name, then remove the annotation:
+
+      ```dart
+      class _C {}
+
+      void f(_C c) {}
+      ```
+
+      If the declaration has a public name and is intended to be internal to the
+      package, then move the annotated declaration into an internal library (in
+      other words, a library inside the `src` directory).
+
+      Otherwise, remove the use of the annotation:
+
+      ```dart
+      class C {}
+      ```
   INVALID_LANGUAGE_VERSION_OVERRIDE_GREATER:
     sharedName: INVALID_LANGUAGE_VERSION_OVERRIDE
-    problemMessage: "The language version override can't specify a version greater than the latest known language version: {0}.{1}"
+    problemMessage: "The language version override can't specify a version greater than the latest known language version: {0}.{1}."
     correctionMessage: Try removing the language version override.
   INVALID_LANGUAGE_VERSION_OVERRIDE_AT_SIGN:
     sharedName: INVALID_LANGUAGE_VERSION_OVERRIDE
-    problemMessage: "The Dart language version override number must begin with '@dart'"
+    problemMessage: "The Dart language version override number must begin with '@dart'."
     correctionMessage: "Specify a Dart language version override with a comment like '// @dart = 2.0'."
     comment: |-
-      Invalid Dart language version comments don't follow the specification [1].
-      If a comment begins with "@dart" or "dart" (letters in any case),
-      followed by optional whitespace, followed by optional non-alphanumeric,
-      non-whitespace characters, followed by optional whitespace, followed by
-      an optional alphabetical character, followed by a digit, then the
-      comment is considered to be an attempt at a language version override
-      comment. If this attempted language version override comment is not a
-      valid language version override comment, it is reported.
+      No parameters.
+    documentation: |-
+      #### Description
 
-      [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+      The analyzer produces this diagnostic when a comment that appears to be an
+      attempt to specify a language version override doesn't conform to the
+      requirements for such a comment. For more information, see
+      [Per-library language version selection](https://dart.dev/guides/language/evolution#per-library-language-version-selection).
+
+      #### Example
+
+      The following code produces this diagnostic because the word `dart` must
+      be lowercase in such a comment and because there's no equal sign between
+      the word `dart` and the version number:
+
+      ```dart
+      [!// @Dart 2.9!]
+      ```
+
+      #### Common fixes
+
+      If the comment is intended to be a language version override, then change
+      the comment to follow the correct format:
+
+      ```dart
+      // @dart = 2.9
+      ```
   INVALID_LANGUAGE_VERSION_OVERRIDE_LOCATION:
     sharedName: INVALID_LANGUAGE_VERSION_OVERRIDE
-    problemMessage: The language version override must be before any declaration or directive.
+    problemMessage: The language version override must be specified before any declaration or directive.
     correctionMessage: Try moving the language version override to the top of the file.
   INVALID_LANGUAGE_VERSION_OVERRIDE_LOWER_CASE:
     sharedName: INVALID_LANGUAGE_VERSION_OVERRIDE
-    problemMessage: "The Dart language version override comment must be specified with the word 'dart' in all lower case"
+    problemMessage: "The Dart language version override comment must be specified with the word 'dart' in all lower case."
     correctionMessage: "Specify a Dart language version override with a comment like '// @dart = 2.0'."
     comment: |-
-      Invalid Dart language version comments don't follow the specification [1].
-      If a comment begins with "@dart" or "dart" (letters in any case),
-      followed by optional whitespace, followed by optional non-alphanumeric,
-      non-whitespace characters, followed by optional whitespace, followed by
-      an optional alphabetical character, followed by a digit, then the
-      comment is considered to be an attempt at a language version override
-      comment. If this attempted language version override comment is not a
-      valid language version override comment, it is reported.
-
-      [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+      No parameters.
   INVALID_LANGUAGE_VERSION_OVERRIDE_NUMBER:
     sharedName: INVALID_LANGUAGE_VERSION_OVERRIDE
     problemMessage: "The Dart language version override comment must be specified with a version number, like '2.0', after the '=' character."
     correctionMessage: "Specify a Dart language version override with a comment like '// @dart = 2.0'."
     comment: |-
-      Invalid Dart language version comments don't follow the specification [1].
-      If a comment begins with "@dart" or "dart" (letters in any case),
-      followed by optional whitespace, followed by optional non-alphanumeric,
-      non-whitespace characters, followed by optional whitespace, followed by
-      an optional alphabetical character, followed by a digit, then the
-      comment is considered to be an attempt at a language version override
-      comment. If this attempted language version override comment is not a
-      valid language version override comment, it is reported.
-
-      [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+      No parameters.
   INVALID_LANGUAGE_VERSION_OVERRIDE_PREFIX:
     sharedName: INVALID_LANGUAGE_VERSION_OVERRIDE
-    problemMessage: "The Dart language version override number can't be prefixed with a letter"
+    problemMessage: "The Dart language version override number can't be prefixed with a letter."
     correctionMessage: "Specify a Dart language version override with a comment like '// @dart = 2.0'."
     comment: |-
-      Invalid Dart language version comments don't follow the specification [1].
-      If a comment begins with "@dart" or "dart" (letters in any case),
-      followed by optional whitespace, followed by optional non-alphanumeric,
-      non-whitespace characters, followed by optional whitespace, followed by
-      an optional alphabetical character, followed by a digit, then the
-      comment is considered to be an attempt at a language version override
-      comment. If this attempted language version override comment is not a
-      valid language version override comment, it is reported.
-
-      [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+      No parameters.
   INVALID_LANGUAGE_VERSION_OVERRIDE_TRAILING_CHARACTERS:
     sharedName: INVALID_LANGUAGE_VERSION_OVERRIDE
-    problemMessage: "The Dart language version override comment can't be followed by any non-whitespace characters"
+    problemMessage: "The Dart language version override comment can't be followed by any non-whitespace characters."
     correctionMessage: "Specify a Dart language version override with a comment like '// @dart = 2.0'."
     comment: |-
-      Invalid Dart language version comments don't follow the specification [1].
-      If a comment begins with "@dart" or "dart" (letters in any case),
-      followed by optional whitespace, followed by optional non-alphanumeric,
-      non-whitespace characters, followed by optional whitespace, followed by
-      an optional alphabetical character, followed by a digit, then the
-      comment is considered to be an attempt at a language version override
-      comment. If this attempted language version override comment is not a
-      valid language version override comment, it is reported.
-
-      [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+      No parameters.
   INVALID_LANGUAGE_VERSION_OVERRIDE_TWO_SLASHES:
     sharedName: INVALID_LANGUAGE_VERSION_OVERRIDE
     problemMessage: The Dart language version override comment must be specified with exactly two slashes.
     correctionMessage: "Specify a Dart language version override with a comment like '// @dart = 2.0'."
     comment: |-
-      Invalid Dart language version comments don't follow the specification [1].
-      If a comment begins with "@dart" or "dart" (letters in any case),
-      followed by optional whitespace, followed by optional non-alphanumeric,
-      non-whitespace characters, followed by optional whitespace, followed by
-      an optional alphabetical character, followed by a digit, then the
-      comment is considered to be an attempt at a language version override
-      comment. If this attempted language version override comment is not a
-      valid language version override comment, it is reported.
-
-      [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+      No parameters.
   INVALID_LANGUAGE_VERSION_OVERRIDE_EQUALS:
     sharedName: INVALID_LANGUAGE_VERSION_OVERRIDE
-    problemMessage: "The Dart language version override comment must be specified with an '=' character"
+    problemMessage: "The Dart language version override comment must be specified with an '=' character."
     correctionMessage: "Specify a Dart language version override with a comment like '// @dart = 2.0'."
     comment: |-
-      Invalid Dart language version comments don't follow the specification [1].
-      If a comment begins with "@dart" or "dart" (letters in any case),
-      followed by optional whitespace, followed by optional non-alphanumeric,
-      non-whitespace characters, followed by optional whitespace, followed by
-      an optional alphabetical character, followed by a digit, then the
-      comment is considered to be an attempt at a language version override
-      comment. If this attempted language version override comment is not a
-      valid language version override comment, it is reported.
-
-      [1] https://github.com/dart-lang/language/blob/master/accepted/future-releases/language-versioning/feature-specification.md#individual-library-language-version-override
+      No parameters.
   INVALID_LITERAL_ANNOTATION:
     problemMessage: Only const constructors can have the `@literal` annotation.
     hasPublishedDocs: true
@@ -16397,8 +17327,8 @@
     documentation: |-
       #### Description
 
-      The analyzer produces this diagnostic when the `@literal` annotation is
-      applied to anything other than a const constructor.
+      The analyzer produces this diagnostic when the `[literal][[meta-literal]]`
+      annotation is applied to anything other than a const constructor.
 
       #### Examples
 
@@ -16568,11 +17498,40 @@
   INVALID_USE_OF_INTERNAL_MEMBER:
     problemMessage: "The member '{0}' can only be used within its package."
     comment: |-
-      This hint is generated anywhere where a member annotated with `@internal`
-      is used outside of the package in which it is declared.
-
       Parameters:
       0: the name of the member
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a reference to a declaration
+      that is annotated with the `[internal][meta-internal]` annotation is found
+      outside the package containing the declaration.
+
+      #### Example
+
+      Given a package `p` that defines a library containing a declaration marked
+      with the `[internal][meta-internal]` annotation:
+
+      ```dart
+      %uri="package:p/src/p.dart"
+      import 'package:meta/meta.dart';
+
+      @internal
+      class C {}
+      ```
+
+      The following code produces this diagnostic because it's referencing the
+      class `C`, which isn't intended to be used outside the package `p`:
+
+      ```dart
+      import 'package:p/src/p.dart';
+
+      void f([!C!] c) {}
+      ```
+
+      #### Common fixes
+
+      Remove the reference to the internal declaration.
   INVALID_USE_OF_PROTECTED_MEMBER:
     problemMessage: "The member '{0}' can only be used within instance members of subclasses of '{1}'."
     comment: |-
@@ -16592,8 +17551,9 @@
       #### Description
 
       The analyzer produces this diagnostic when an instance member that is
-      annotated with `visibleForOverriding` is referenced outside the library in
-      which it's declared for any reason other than to override it.
+      annotated with `[visibleForOverriding][meta-visibleForOverriding]` is
+      referenced outside the library in which it's declared for any reason other
+      than to override it.
 
       #### Example
 
@@ -16657,8 +17617,9 @@
     documentation: |-
       #### Description
 
-      The analyzer produces this diagnostic when either the `@visibleForTemplate`
-      or `@visibleForTesting` annotation is applied to a non-public declaration.
+      The analyzer produces this diagnostic when either the `visibleForTemplate`
+      or `[visibleForTesting][meta-visibleForTesting]` annotation is applied to
+      a non-public declaration.
 
       #### Example
 
@@ -16702,9 +17663,10 @@
       #### Description
 
       The analyzer produces this diagnostic when anything other than a public
-      instance member of a class is annotated with `visibleForOverriding`.
-      Because only public instance members can be overridden outside the defining
-      library, there's no value to annotating any other declarations.
+      instance member of a class is annotated with
+      `[visibleForOverriding][meta-visibleForOverriding]`. Because only public
+      instance members can be overridden outside the defining library, there's
+      no value to annotating any other declarations.
 
       #### Example
 
@@ -16828,9 +17790,9 @@
       #### Description
 
       The analyzer produces this diagnostic when the superclass constraint of a
-      mixin is a class from a different package that was marked as `@sealed`.
-      Classes that are sealed can't be extended, implemented, mixed in, or used
-      as a superclass constraint.
+      mixin is a class from a different package that was marked as
+      `[sealed][meta-sealed]`. Classes that are sealed can't be extended,
+      implemented, mixed in, or used as a superclass constraint.
 
       #### Example
 
@@ -16869,8 +17831,8 @@
 
       The analyzer produces this diagnostic when an immutable class defines one
       or more instance fields that aren't final. A class is immutable if it's
-      marked as being immutable using the annotation `@immutable` or if it's a
-      subclass of an immutable class.
+      marked as being immutable using the annotation
+      `[immutable][meta-immutable]` or if it's a subclass of an immutable class.
 
       #### Example
 
@@ -16925,8 +17887,8 @@
       #### Description
 
       The analyzer produces this diagnostic when a method that overrides a method
-      that is annotated as `@mustCallSuper` doesn't invoke the overridden method
-      as required.
+      that is annotated as `[mustCallSuper][meta-mustCallSuper]` doesn't invoke
+      the overridden method as required.
 
       #### Example
 
@@ -16991,10 +17953,10 @@
       #### Description
 
       The analyzer produces this diagnostic when a constructor that has the
-      `@literal` annotation is invoked without using the `const` keyword, but all
-      of the arguments to the constructor are constants. The annotation indicates
-      that the constructor should be used to create a constant value whenever
-      possible.
+      `[literal][meta-literal]` annotation is invoked without using the `const`
+      keyword, but all of the arguments to the constructor are constants. The
+      annotation indicates that the constructor should be used to create a
+      constant value whenever possible.
 
       #### Example
 
@@ -17121,8 +18083,42 @@
   NULL_CHECK_ALWAYS_FAILS:
     problemMessage: "This null-check will always throw an exception because the expression will always evaluate to 'null'."
     comment: |-
-      This hint indicates that a null literal is null-checked with `!`, but null
-      is never not null.
+      No parameters.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when the null check operator (`!`)
+      is used on an expression whose value can only be `null`. In such a case
+      the operator always throws an exception, which likely isn't the intended
+      behavior.
+
+      #### Example
+
+      The following code produces this diagnostic because the function `g` will
+      always return `null`, which means that the null check in `f` will always
+      throw:
+
+      ```dart
+      void f() {
+        [!g()!!];
+      }
+
+      Null g() => null;
+      ```
+
+      #### Common fixes
+
+      If you intend to always throw an exception, then replace the null check
+      with an explicit `throw` expression to make the intent more clear:
+
+      ```dart
+      void f() {
+        g();
+        throw TypeError();
+      }
+
+      Null g() => null;
+      ```
   OVERRIDE_ON_NON_OVERRIDING_FIELD:
     sharedName: OVERRIDE_ON_NON_OVERRIDING_MEMBER
     problemMessage: "The field doesn't override an inherited getter or setter."
@@ -17221,8 +18217,56 @@
     problemMessage: "'{0}' is annotated with 'doNotStore' and shouldn't be returned unless '{1}' is also annotated."
     correctionMessage: "Annotate '{1}' with 'doNotStore'."
     comment: |-
-      Users should not return values marked `@doNotStore` from functions,
-      methods or getters not marked `@doNotStore`.
+      Parameters:
+      0: the name of the annotated function being invoked
+      1: the name of the function containing the return
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a value that is annotated with
+      the `[doNotStore][meta-doNotStore]` annotation is returned from a method,
+      getter, or function that doesn't have the same annotation.
+
+      #### Example
+
+      The following code produces this diagnostic because the result of invoking
+      `f` shouldn't be stored, but the function `g` isn't annotated to preserve
+      that semantic:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      @doNotStore
+      int f() => 0;
+
+      int g() => [!f()!];
+      ```
+
+      #### Common fixes
+
+      If the value that shouldn't be stored is the correct value to return, then
+      mark the function with the `[doNotStore][meta-doNotStore]` annotation:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      @doNotStore
+      int f() => 0;
+
+      @doNotStore
+      int g() => f();
+      ```
+
+      Otherwise, return a different value from the function:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      @doNotStore
+      int f() => 0;
+
+      int g() => 0;
+      ```
   SDK_VERSION_ASYNC_EXPORTED_FROM_CORE:
     problemMessage: "The class '{0}' wasn't exported from 'dart:core' until version 2.1, but this code is required to be able to run on earlier versions."
     correctionMessage: "Try either importing 'dart:async' or updating the SDK constraints."
@@ -17881,10 +18925,10 @@
       #### Description
 
       The analyzer produces this diagnostic when a sealed class (one that either
-      has the `@sealed` annotation or inherits or mixes in a sealed class) is
-      referenced in either the `extends`, `implements`, or `with` clause of a
-      class or mixin declaration if the declaration isn't in the same package as
-      the sealed class.
+      has the `[sealed][meta-sealed]` annotation or inherits or mixes in a
+      sealed class) is referenced in either the `extends`, `implements`, or
+      `with` clause of a class or mixin declaration if the declaration isn't in
+      the same package as the sealed class.
 
       #### Example
 
@@ -18108,8 +19152,8 @@
       #### Description
 
       The analyzer produces this diagnostic when an annotation of the form
-      `@UnusedResult.unless(parameterDefined: parameterName)` specifies a
-      parameter name that isn't defined by the annotated function.
+      `[UseResult][meta-UseResult].unless(parameterDefined: parameterName)`
+      specifies a parameter name that isn't defined by the annotated function.
 
       #### Example
 
@@ -18753,16 +19797,16 @@
       #### Description
 
       The analyzer produces this diagnostic when a function annotated with
-      `useResult` is invoked, and the value returned by that function isn't used.
-      The value is considered to be used if a member of the value is invoked, if
-      the value is passed to another function, or if the value is assigned to a
-      variable or field.
+      `[useResult][meta-useResult]` is invoked, and the value returned by that
+      function isn't used. The value is considered to be used if a member of the
+      value is invoked, if the value is passed to another function, or if the
+      value is assigned to a variable or field.
 
       #### Example
 
       The following code produces this diagnostic because the invocation of
       `c.a()` isn't used, even though the method `a` is annotated with
-      `useResult`:
+      `[useResult][meta-useResult]`:
 
       ```dart
       import 'package:meta/meta.dart';
diff --git a/pkg/analyzer/test/src/diagnostics/assignment_of_do_not_store_test.dart b/pkg/analyzer/test/src/diagnostics/assignment_of_do_not_store_test.dart
index 8ae77f0..a0c388c 100644
--- a/pkg/analyzer/test/src/diagnostics/assignment_of_do_not_store_test.dart
+++ b/pkg/analyzer/test/src/diagnostics/assignment_of_do_not_store_test.dart
@@ -73,6 +73,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_classMemberVariable() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
@@ -107,6 +108,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_classStaticVariable() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
@@ -197,6 +199,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_topLevelVariable() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
@@ -212,6 +215,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_topLevelVariable_assignment_field() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
@@ -228,6 +232,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_topLevelVariable_assignment_functionExpression() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
@@ -273,6 +278,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_topLevelVariable_binaryExpression() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
@@ -310,6 +316,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_topLevelVariable_ternary() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
diff --git a/pkg/analyzer/test/src/diagnostics/inference_failure_on_function_invocation_test.dart b/pkg/analyzer/test/src/diagnostics/inference_failure_on_function_invocation_test.dart
index e048093..67cc9aa 100644
--- a/pkg/analyzer/test/src/diagnostics/inference_failure_on_function_invocation_test.dart
+++ b/pkg/analyzer/test/src/diagnostics/inference_failure_on_function_invocation_test.dart
@@ -47,6 +47,7 @@
 ''');
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_functionType_optionalTypeArgs() async {
     await assertNoErrorsInCode('''
 import 'package:meta/meta.dart';
diff --git a/pkg/analyzer/test/src/diagnostics/return_of_do_not_store_test.dart b/pkg/analyzer/test/src/diagnostics/return_of_do_not_store_test.dart
index bd97b34..b464d2c 100644
--- a/pkg/analyzer/test/src/diagnostics/return_of_do_not_store_test.dart
+++ b/pkg/analyzer/test/src/diagnostics/return_of_do_not_store_test.dart
@@ -9,8 +9,8 @@
 
 main() {
   defineReflectiveSuite(() {
-    defineReflectiveTests(ReturnOfDoNotStoreTest);
     defineReflectiveTests(ReturnOfDoNotStoreInTestsTest);
+    defineReflectiveTests(ReturnOfDoNotStoreTest);
   });
 }
 
@@ -22,6 +22,7 @@
     writeTestPackageConfigWithMeta();
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_noHintsInTestDir() async {
     // Code that is in a test dir (the default for PubPackageResolutionTests)
     // should not trigger the hint.
@@ -58,6 +59,7 @@
     writeTestPackageConfigWithMeta();
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_returnFromClosureInFunction() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
@@ -74,6 +76,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_returnFromFunction() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
@@ -96,6 +99,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_returnFromGetter() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
@@ -117,6 +121,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_returnFromGetter_binaryExpression() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
@@ -134,6 +139,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_returnFromGetter_ternary() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
@@ -153,6 +159,7 @@
     ]);
   }
 
+  @FailingTest(issue: 'https://github.com/dart-lang/sdk/issues/48476')
   test_returnFromMethod() async {
     await assertErrorsInCode('''
 import 'package:meta/meta.dart';
diff --git a/pkg/analyzer/test/verify_diagnostics_test.dart b/pkg/analyzer/test/verify_diagnostics_test.dart
index 873f700..e56d8b6 100644
--- a/pkg/analyzer/test/verify_diagnostics_test.dart
+++ b/pkg/analyzer/test/verify_diagnostics_test.dart
@@ -423,6 +423,9 @@
   }
 
   @override
+  String get testPackageRootPath => '$workspaceRootPath/docTest';
+
+  @override
   void setUp() {
     super.setUp();
     _createAuxiliaryFiles(snippet.auxiliaryFiles);
diff --git a/pkg/analyzer/tool/diagnostics/diagnostics.md b/pkg/analyzer/tool/diagnostics/diagnostics.md
index ebd48c9..3483786 100644
--- a/pkg/analyzer/tool/diagnostics/diagnostics.md
+++ b/pkg/analyzer/tool/diagnostics/diagnostics.md
@@ -21,13 +21,17 @@
 * [definite assignment][]
 * [mixin application][]
 * [override inference][]
+* [part file][]
 * [potentially non-nullable][]
+* [public library][]
 
 [constant context]: #constant-context
 [definite assignment]: #definite-assignment
 [mixin application]: #mixin-application
 [override inference]: #override-inference
+[part file]: #part-file
 [potentially non-nullable]: #potentially-non-nullable
+[public library]: #public-library
 
 ### Constant context
 
@@ -248,6 +252,10 @@
 It is an error if none of the overridden methods has a function type that is a
 supertype of all the other overridden methods.
 
+### Part file
+
+A part file is a Dart source file that contains a `part of` directive.
+
 ### Potentially non-nullable
 
 A type is _potentially non-nullable_ if it's either explicitly non-nullable or
@@ -264,12 +272,30 @@
 given a declaration of `class C<T> {}`, the type `C` could be used with a
 non-nullable type argument as in `C<int>`.
 
+### Public library
+
+A public library is a library that is located inside the package's `lib`
+directory but not inside the `lib/src` directory.
+
 ## Diagnostics
 
 The analyzer produces the following diagnostics for code that
 doesn't conform to the language specification or
 that might work in unexpected ways.
 
+[meta-doNotStore]: https://pub.dev/documentation/meta/latest/meta/doNotStore-constant.html
+[meta-factory]: https://pub.dev/documentation/meta/latest/meta/factory-constant.html
+[meta-immutable]: https://pub.dev/documentation/meta/latest/meta/immutable-constant.html
+[meta-internal]: https://pub.dev/documentation/meta/latest/meta/internal-constant.html
+[meta-literal]: https://pub.dev/documentation/meta/latest/meta/literal-constant.html
+[meta-mustCallSuper]: https://pub.dev/documentation/meta/latest/meta/mustCallSuper-constant.html
+[meta-optionalTypeArgs]: https://pub.dev/documentation/meta/latest/meta/optionalTypeArgs-constant.html
+[meta-sealed]: https://pub.dev/documentation/meta/latest/meta/sealed-constant.html
+[meta-useResult]: https://pub.dev/documentation/meta/latest/meta/useResult-constant.html
+[meta-UseResult]: https://pub.dev/documentation/meta/latest/meta/UseResult-class.html
+[meta-visibleForOverriding]: https://pub.dev/documentation/meta/latest/meta/visibleForOverriding-constant.html
+[meta-visibleForTesting]: https://pub.dev/documentation/meta/latest/meta/visibleForTesting-constant.html
+
 ### abstract_field_initializer
 
 _Abstract fields can't have initializers._
@@ -1025,6 +1051,37 @@
     - image.gif
 ```
 
+### assignment_of_do_not_store
+
+_'{0}' is marked 'doNotStore' and shouldn't be assigned to a field or top-level
+variable._
+
+#### Description
+
+The analyzer produces this diagnostic when the value of a function
+(including methods and getters) that is explicitly or implicitly marked by
+the `[doNotStore][meta-doNotStore]` annotation is stored in either a field
+or top-level variable.
+
+#### Example
+
+The following code produces this diagnostic because the value of the
+function `f` is being stored in the top-level variable `x`:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+@doNotStore
+int f() => 1;
+
+var x = [!f()!];
+{% endprettify %}
+
+#### Common fixes
+
+Replace references to the field or variable with invocations of the
+function producing the value.
+
 ### assignment_to_const
 
 _Constant variables can't be assigned a value._
@@ -1492,6 +1549,45 @@
 }
 {% endprettify %}
 
+### body_might_complete_normally_nullable
+
+_This function has a nullable return type of '{0}', but ends without returning a
+value._
+
+#### Description
+
+The analyzer produces this diagnostic when a method or function can
+implicitly return `null` by falling off the end. While this is valid Dart
+code, it's better for the return of `null` to be explicit.
+
+#### Example
+
+The following code produces this diagnostic because the function `f`
+implicitly returns `null`:
+
+{% prettify dart tag=pre+code %}
+String? [!f!]() {}
+{% endprettify %}
+
+#### Common fixes
+
+If the return of `null` is intentional, then make it explicit:
+
+{% prettify dart tag=pre+code %}
+String? f() {
+  return null;
+}
+{% endprettify %}
+
+If the function should return a non-null value along that path, then add
+the missing return statement:
+
+{% prettify dart tag=pre+code %}
+String? f() {
+  return '';
+}
+{% endprettify %}
+
 ### break_label_on_switch_member
 
 _A break label resolves to the 'case' or 'default' statement._
@@ -2796,6 +2892,35 @@
 C<T> newC<T>() => C<T>();
 {% endprettify %}
 
+### continue_label_on_switch
+
+_A `continue` label resolves to a `switch` statement, but the label must be on a
+loop or a switch member._
+
+#### Description
+
+The analyzer produces this diagnostic when the label in a `continue`
+statement resolves to a label on a `switch` statement.
+
+#### Example
+
+The following code produces this diagnostic because the label `l`, used to
+label a `switch` statement, is used in the `continue` statement:
+
+{% prettify dart tag=pre+code %}
+void f(int i) {
+  l: switch (i) {
+    case 0:
+      continue [!l!];
+  }
+}
+{% endprettify %}
+
+#### Common fixes
+
+Find a different way to achieve the control flow you need; for example, by
+introducing a loop that re-executes the `switch` statement.
+
 ### creation_of_struct_or_union
 
 _Subclasses of 'Struct' and 'Union' are backed by native memory, and can't be
@@ -3507,6 +3632,59 @@
 documentation for deprecated declarations should indicate what code to use
 in place of the deprecated code.
 
+### deprecated_new_in_comment_reference
+
+_Using the 'new' keyword in a comment reference is deprecated._
+
+#### Description
+
+The analyzer produces this diagnostic when a comment reference (the name
+of a declaration enclosed in square brackets in a documentation comment)
+uses the keyword `new` to refer to a constructor. This form is deprecated.
+
+#### Examples
+
+The following code produces this diagnostic because the unnamed
+constructor is being referenced using `new C`:
+
+{% prettify dart tag=pre+code %}
+/// See [[!new!] C].
+class C {
+  C();
+}
+{% endprettify %}
+
+The following code produces this diagnostic because the constructor named
+`c` is being referenced using `new C.c`:
+
+{% prettify dart tag=pre+code %}
+/// See [[!new!] C.c].
+class C {
+  C.c();
+}
+{% endprettify %}
+
+#### Common fixes
+
+If you're referencing a named constructor, then remove the keyword `new`:
+
+{% prettify dart tag=pre+code %}
+/// See [C.c].
+class C {
+  C.c();
+}
+{% endprettify %}
+
+If you're referencing the unnamed constructor, then remove the keyword
+`new` and append `.new` after the class name:
+
+{% prettify dart tag=pre+code %}
+/// See [C.new].
+class C {
+  C.c();
+}
+{% endprettify %}
+
 ### deprecated_subtype_of_function
 
 _Extending 'Function' is deprecated._
@@ -3540,6 +3718,46 @@
 class F {}
 {% endprettify %}
 
+### disallowed_type_instantiation_expression
+
+_Only a generic type, generic function, generic instance method, or generic
+constructor can have type arguments._
+
+#### Description
+
+The analyzer produces this diagnostic when an expression with a value that
+is anything other than one of the allowed kinds of values is followed by
+type arguments. The allowed kinds of values are:
+- generic types,
+- generic constructors, and
+- generic functions, including top-level functions, static and instance
+  members, and local functions.
+
+#### Example
+
+The following code produces this diagnostic because `i` is a top-level
+variable, which isn't one of the allowed cases:
+
+{% prettify dart tag=pre+code %}
+int i = 1;
+
+void f() {
+  print([!i!]<int>);
+}
+{% endprettify %}
+
+#### Common fixes
+
+If the referenced value is correct, then remove the type arguments:
+
+{% prettify dart tag=pre+code %}
+int i = 1;
+
+void f() {
+  print(i);
+}
+{% endprettify %}
+
 ### duplicate_constructor
 
 _The constructor with name '{0}' is already defined._
@@ -3981,6 +4199,44 @@
 class C {}
 {% endprettify %}
 
+### enum_constant_same_name_as_enclosing
+
+_The name of the enum constant 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.
+
+#### Example
+
+The following code produces this diagnostic because the enum constant `E`
+has the same name as the enclosing enum `E`:
+
+{% prettify dart tag=pre+code %}
+enum E {
+  [!E!]
+}
+{% endprettify %}
+
+#### Common fixes
+
+If the name of the enum is correct, then rename the constant:
+
+{% prettify dart tag=pre+code %}
+enum E {
+  e
+}
+{% endprettify %}
+
+If the name of the constant is correct, then rename the enum:
+
+{% prettify dart tag=pre+code %}
+enum F {
+  E
+}
+{% endprettify %}
+
 ### equal_elements_in_const_set
 
 _Two elements in a constant set literal can't be equal._
@@ -4752,6 +5008,56 @@
 If there are multiple cascaded accesses, you'll need to duplicate the
 extension override for each one.
 
+### external_with_initializer
+
+_External fields can't have initializers._
+
+_External variables can't have initializers._
+
+#### Description
+
+The analyzer produces this diagnostic when a field or variable marked with
+the keyword `external` has an initializer, or when an external field is
+initialized in a constructor.
+
+#### Examples
+
+The following code produces this diagnostic because the external field `x`
+is assigned a value in an initializer:
+
+{% prettify dart tag=pre+code %}
+class C {
+  external int x;
+  C() : [!x!] = 0;
+}
+{% endprettify %}
+
+The following code produces this diagnostic because the external field `x`
+has an initializer:
+
+{% prettify dart tag=pre+code %}
+class C {
+  external final int [!x!] = 0;
+}
+{% endprettify %}
+
+The following code produces this diagnostic because the external top level
+variable `x` has an initializer:
+
+{% prettify dart tag=pre+code %}
+external final int [!x!] = 0;
+{% endprettify %}
+
+#### Common fixes
+
+Remove the initializer:
+
+{% prettify dart tag=pre+code %}
+class C {
+  external final int x;
+}
+{% endprettify %}
+
 ### extra_annotation_on_struct_field
 
 _Fields in a struct class must have exactly one annotation indicating the native
@@ -5179,6 +5485,46 @@
 }
 {% endprettify %}
 
+### field_initializer_outside_constructor
+
+_Field formal parameters can only be used in a constructor._
+
+_Initializing formal parameters can only be used in constructors._
+
+#### Description
+
+The analyzer produces this diagnostic when an initializing formal
+parameter is used in the parameter list for anything other than a
+constructor.
+
+#### Example
+
+The following code produces this diagnostic because the initializing
+formal parameter `this.x` is being used in the method `m`:
+
+{% prettify dart tag=pre+code %}
+class A {
+  int x = 0;
+
+  m([[!this.x!] = 0]) {}
+}
+{% endprettify %}
+
+#### Common fixes
+
+Replace the initializing formal parameter with a normal parameter and
+assign the field within the body of the method:
+
+{% prettify dart tag=pre+code %}
+class A {
+  int x = 0;
+
+  m([int x = 0]) {
+    this.x = x;
+  }
+}
+{% endprettify %}
+
 ### field_initializer_redirecting_constructor
 
 _The redirecting constructor can't have a field initializer._
@@ -6198,7 +6544,8 @@
 {% endprettify %}
 
 If type arguments shouldn't be required for the class, then mark the class
-with the `@optionalTypeArgs` annotation (from `package:meta`):
+with the `[optionalTypeArgs][meta-optionalTypeArgs]` annotation (from
+`package:meta`):
 
 ### import_internal_library
 
@@ -6222,6 +6569,79 @@
 
 Remove the import directive.
 
+### import_of_legacy_library_into_null_safe
+
+_The library '{0}' is legacy, and shouldn't be imported into a null safe
+library._
+
+#### Description
+
+The analyzer produces this diagnostic when a library that is null safe
+imports a library that isn't null safe.
+
+#### Example
+
+Given a file named `a.dart` that contains the following:
+
+{% prettify dart tag=pre+code %}
+// @dart = 2.9
+
+class A {}
+{% endprettify %}
+
+The following code produces this diagnostic because a library that null
+safe is importing a library that isn't null safe:
+
+{% prettify dart tag=pre+code %}
+import [!'a.dart'!];
+
+A? f() => null;
+{% endprettify %}
+
+#### Common fixes
+
+If you can migrate the imported library to be null safe, then migrate it
+and update or remove the migrated library's language version.
+
+If you can't migrate the imported library, then the importing library
+needs to have a language version that is before 2.12, when null safety was
+enabled by default.
+
+### import_of_non_library
+
+_The imported library '{0}' can't have a part-of directive._
+
+#### Description
+
+The analyzer produces this diagnostic when a [part file][] is imported
+into a library.
+
+#### Example
+
+Given a [part file][] named `part.dart` containing the following:
+
+{% prettify dart tag=pre+code %}
+part of lib;
+
+class C{}
+{% endprettify %}
+
+The following code produces this diagnostic because imported files can't
+have a part-of directive:
+
+{% prettify dart tag=pre+code %}
+library lib;
+
+import [!'part.dart'!];
+
+C c = C();
+{% endprettify %}
+
+#### Common fixes
+
+Import the library that contains the [part file][] rather than the
+[part file][] itself.
+
 ### inconsistent_inheritance
 
 _Superinterfaces don't have a valid override for '{0}': {1}._
@@ -6270,6 +6690,47 @@
 }
 {% endprettify %}
 
+### inconsistent_language_version_override
+
+_Parts must have exactly the same language version override as the library._
+
+#### Description
+
+The analyzer produces this diagnostic when a [part file][] has a language
+version override comment that specifies a different language version than
+the one being used for the library to which the part belongs.
+
+#### Example
+
+Given a [part file][] named `part.dart` that contains the following:
+
+{% prettify dart tag=pre+code %}
+// @dart = 2.6
+part of 'test.dart';
+{% endprettify %}
+
+The following code produces this diagnostic because the parts of a library
+must have the same language version as the defining compilation unit:
+
+{% prettify dart tag=pre+code %}
+// @dart = 2.5
+part [!'part.dart'!];
+{% endprettify %}
+
+#### Common fixes
+
+Remove the language version override from the [part file][], so that it
+implicitly uses the same version as the defining compilation unit:
+
+{% prettify dart tag=pre+code %}
+part of 'test.dart';
+{% endprettify %}
+
+If necessary, either adjust the language version override in the defining
+compilation unit to be appropriate for the code in the part, or migrate
+the code in the [part file][] to be consistent with the new language
+version.
+
 ### initializer_for_non_existent_field
 
 _'{0}' isn't a field in the enclosing class._
@@ -6918,6 +7379,31 @@
 void f() {}
 {% endprettify %}
 
+### invalid_annotation_target
+
+_The annotation '{0}' can only be used on {1}._
+
+#### Description
+
+The analyzer produces this diagnostic when an annotation is applied to a
+kind of declaration that it doesn't support.
+
+#### Example
+
+The following code produces this diagnostic because the `optionalTypeArgs`
+annotation isn't defined to be valid for top-level variables:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+@[!optionalTypeArgs!]
+int x = 0;
+{% endprettify %}
+
+#### Common fixes
+
+Remove the annotation from the declaration.
+
 ### invalid_assignment
 
 _A value of type '{0}' can't be assigned to a variable of type '{1}'._
@@ -7055,6 +7541,87 @@
 }
 {% endprettify %}
 
+### invalid_export_of_internal_element
+
+_The member '{0}' can't be exported as a part of a package's public API._
+
+#### Description
+
+The analyzer produces this diagnostic when a [public library][] exports a
+declaration that is marked with the `[internal][meta-internal]`
+annotation.
+
+#### Example
+
+Given a file named `a.dart` in the `src` directory that contains:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+@internal class One {}
+{% endprettify %}
+
+The following code, when found in a [public library][] produces this
+diagnostic because the `export` directive is exporting a name that is only
+intended to be used internally:
+
+{% prettify dart tag=pre+code %}
+[!export 'src/a.dart';!]
+{% endprettify %}
+
+#### Common fixes
+
+If the export is needed, then add a `hide` clause to hide the internal
+names:
+
+{% prettify dart tag=pre+code %}
+export 'src/a.dart' hide One;
+{% endprettify %}
+
+If the export isn't needed, then remove it.
+
+### invalid_export_of_internal_element_indirectly
+
+_The member '{0}' can't be exported as a part of a package's public API, but is
+indirectly exported as part of the signature of '{1}'._
+
+#### Description
+
+The analyzer produces this diagnostic when a [public library][] exports a
+top-level function  with a return type or at least one parameter type that
+is marked with the `[internal][meta-internal]` annotation.
+
+#### Example
+
+Given a file named `a.dart` in the `src` directory that contains the
+following:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+@internal
+typedef IntFunction = int Function();
+
+int f(IntFunction g) => g();
+{% endprettify %}
+
+The following code produces this diagnostic because the function `f` has a
+parameter of type `IntFunction`, and `IntFunction` is only intended to be
+used internally:
+
+{% prettify dart tag=pre+code %}
+[!export 'src/a.dart' show f;!]
+{% endprettify %}
+
+#### Common fixes
+
+If the function must be public, then make all the types in the function's
+signature public types.
+
+If the function doesn't need to be exported, then stop exporting it,
+either by removing it from the `show` clause, adding it to the `hide`
+clause, or by removing the export.
+
 ### invalid_extension_argument_count
 
 _Extension overrides must have exactly one argument: the value of 'this' in the
@@ -7108,6 +7675,90 @@
 }
 {% endprettify %}
 
+### invalid_factory_method_decl
+
+_Factory method '{0}' must have a return type._
+
+#### Description
+
+The analyzer produces this diagnostic when a method that is annotated with
+the `[factory][meta-factory]` annotation has a return type of `void`.
+
+#### Example
+
+The following code produces this diagnostic because the method `createC`
+is annotated with the `[factory][meta-factory]` annotation but doesn't
+return any value:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+class Factory {
+  @factory
+  void [!createC!]() {}
+}
+
+class C {}
+{% endprettify %}
+
+#### Common fixes
+
+Change the return type to something other than `void`:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+class Factory {
+  @factory
+  C createC() => C();
+}
+
+class C {}
+{% endprettify %}
+
+### invalid_factory_method_impl
+
+_Factory method '{0}' doesn't return a newly allocated object._
+
+#### Description
+
+The analyzer produces this diagnostic when a method that is annotated with
+the `[factory][meta-factory]` annotation doesn't return a newly allocated
+object.
+
+#### Example
+
+The following code produces this diagnostic because the method `createC`
+returns the value of a field rather than a newly created instance of `C`:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+class Factory {
+  C c = C();
+
+  @factory
+  C [!createC!]() => c;
+}
+
+class C {}
+{% endprettify %}
+
+#### Common fixes
+
+Change the method to return a newly created instance of the return type:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+class Factory {
+  @factory
+  C createC() => C();
+}
+
+class C {}
+{% endprettify %}
+
 ### invalid_factory_name_not_a_class
 
 _The name of a factory constructor must be the same as the name of the
@@ -7326,14 +7977,124 @@
 typedef F = int Function(int Function(String));
 {% endprettify %}
 
+### invalid_internal_annotation
+
+_Only public elements in a package's private API can be annotated as being
+internal._
+
+#### Description
+
+The analyzer produces this diagnostic when a declaration is annotated with
+the `[internal][meta-internal]` annotation and that declaration is either
+in a [public library][] or has a private name.
+
+#### Example
+
+The following code, when in a [public library][], produces this diagnostic
+because the `[internal][meta-internal]` annotation can't be applied to
+declarations in a [public library][]:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+[!@internal!]
+class C {}
+{% endprettify %}
+
+The following code, whether in a public or internal library, produces this
+diagnostic because the `[internal][meta-internal]` annotation can't be
+applied to declarations with private names:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+[!@internal!]
+class _C {}
+
+void f(_C c) {}
+{% endprettify %}
+
+#### Common fixes
+
+If the declaration has a private name, then remove the annotation:
+
+{% prettify dart tag=pre+code %}
+class _C {}
+
+void f(_C c) {}
+{% endprettify %}
+
+If the declaration has a public name and is intended to be internal to the
+package, then move the annotated declaration into an internal library (in
+other words, a library inside the `src` directory).
+
+Otherwise, remove the use of the annotation:
+
+{% prettify dart tag=pre+code %}
+class C {}
+{% endprettify %}
+
+### invalid_language_version_override
+
+_The Dart language version override comment can't be followed by any
+non-whitespace characters._
+
+_The Dart language version override comment must be specified with a version
+number, like '2.0', after the '=' character._
+
+_The Dart language version override comment must be specified with an '='
+character._
+
+_The Dart language version override comment must be specified with exactly two
+slashes._
+
+_The Dart language version override comment must be specified with the word
+'dart' in all lower case._
+
+_The Dart language version override number can't be prefixed with a letter._
+
+_The Dart language version override number must begin with '@dart'._
+
+_The language version override can't specify a version greater than the latest
+known language version: {0}.{1}._
+
+_The language version override must be specified before any declaration or
+directive._
+
+#### Description
+
+The analyzer produces this diagnostic when a comment that appears to be an
+attempt to specify a language version override doesn't conform to the
+requirements for such a comment. For more information, see
+[Per-library language version selection](https://dart.dev/guides/language/evolution#per-library-language-version-selection).
+
+#### Example
+
+The following code produces this diagnostic because the word `dart` must
+be lowercase in such a comment and because there's no equal sign between
+the word `dart` and the version number:
+
+{% prettify dart tag=pre+code %}
+[!// @Dart 2.9!]
+{% endprettify %}
+
+#### Common fixes
+
+If the comment is intended to be a language version override, then change
+the comment to follow the correct format:
+
+{% prettify dart tag=pre+code %}
+// @dart = 2.9
+{% endprettify %}
+
 ### invalid_literal_annotation
 
 _Only const constructors can have the `@literal` annotation._
 
 #### Description
 
-The analyzer produces this diagnostic when the `@literal` annotation is
-applied to anything other than a const constructor.
+The analyzer produces this diagnostic when the `[literal][[meta-literal]]`
+annotation is applied to anything other than a const constructor.
 
 #### Examples
 
@@ -7805,6 +8566,41 @@
 }
 {% endprettify %}
 
+### invalid_use_of_internal_member
+
+_The member '{0}' can only be used within its package._
+
+#### Description
+
+The analyzer produces this diagnostic when a reference to a declaration
+that is annotated with the `[internal][meta-internal]` annotation is found
+outside the package containing the declaration.
+
+#### Example
+
+Given a package `p` that defines a library containing a declaration marked
+with the `[internal][meta-internal]` annotation:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+@internal
+class C {}
+{% endprettify %}
+
+The following code produces this diagnostic because it's referencing the
+class `C`, which isn't intended to be used outside the package `p`:
+
+{% prettify dart tag=pre+code %}
+import 'package:p/src/p.dart';
+
+void f([!C!] c) {}
+{% endprettify %}
+
+#### Common fixes
+
+Remove the reference to the internal declaration.
+
 ### invalid_use_of_null_value
 
 _An expression whose value is always 'null' can't be dereferenced._
@@ -7843,8 +8639,9 @@
 #### Description
 
 The analyzer produces this diagnostic when an instance member that is
-annotated with `visibleForOverriding` is referenced outside the library in
-which it's declared for any reason other than to override it.
+annotated with `[visibleForOverriding][meta-visibleForOverriding]` is
+referenced outside the library in which it's declared for any reason other
+than to override it.
 
 #### Example
 
@@ -7884,8 +8681,9 @@
 
 #### Description
 
-The analyzer produces this diagnostic when either the `@visibleForTemplate`
-or `@visibleForTesting` annotation is applied to a non-public declaration.
+The analyzer produces this diagnostic when either the `visibleForTemplate`
+or `[visibleForTesting][meta-visibleForTesting]` annotation is applied to
+a non-public declaration.
 
 #### Example
 
@@ -7930,9 +8728,10 @@
 #### Description
 
 The analyzer produces this diagnostic when anything other than a public
-instance member of a class is annotated with `visibleForOverriding`.
-Because only public instance members can be overridden outside the defining
-library, there's no value to annotating any other declarations.
+instance member of a class is annotated with
+`[visibleForOverriding][meta-visibleForOverriding]`. Because only public
+instance members can be overridden outside the defining library, there's
+no value to annotating any other declarations.
 
 #### Example
 
@@ -9537,9 +10336,9 @@
 #### Description
 
 The analyzer produces this diagnostic when the superclass constraint of a
-mixin is a class from a different package that was marked as `@sealed`.
-Classes that are sealed can't be extended, implemented, mixed in, or used
-as a superclass constraint.
+mixin is a class from a different package that was marked as
+`[sealed][meta-sealed]`. Classes that are sealed can't be extended,
+implemented, mixed in, or used as a superclass constraint.
 
 #### Example
 
@@ -9594,6 +10393,40 @@
 
 Otherwise, remove the type from the `on` clause.
 
+### multiple_redirecting_constructor_invocations
+
+_Constructors can have only one 'this' redirection, at most._
+
+#### Description
+
+The analyzer produces this diagnostic when a constructor redirects to more
+than one other constructor in the same class (using `this`).
+
+#### Example
+
+The following code produces this diagnostic because the unnamed
+constructor in `C` is redirecting to both `this.a` and `this.b`:
+
+{% prettify dart tag=pre+code %}
+class C {
+  C() : this.a(), [!this.b()!];
+  C.a();
+  C.b();
+}
+{% endprettify %}
+
+#### Common fixes
+
+Remove all but one of the redirections:
+
+{% prettify dart tag=pre+code %}
+class C {
+  C() : this.a();
+  C.a();
+  C.b();
+}
+{% endprettify %}
+
 ### multiple_super_initializers
 
 _A constructor can have at most one 'super' initializer._
@@ -9798,8 +10631,8 @@
 
 The analyzer produces this diagnostic when an immutable class defines one
 or more instance fields that aren't final. A class is immutable if it's
-marked as being immutable using the annotation `@immutable` or if it's a
-subclass of an immutable class.
+marked as being immutable using the annotation
+`[immutable][meta-immutable]` or if it's a subclass of an immutable class.
 
 #### Example
 
@@ -9853,8 +10686,8 @@
 #### Description
 
 The analyzer produces this diagnostic when a method that overrides a method
-that is annotated as `@mustCallSuper` doesn't invoke the overridden method
-as required.
+that is annotated as `[mustCallSuper][meta-mustCallSuper]` doesn't invoke
+the overridden method as required.
 
 #### Example
 
@@ -10663,10 +11496,10 @@
 #### Description
 
 The analyzer produces this diagnostic when a constructor that has the
-`@literal` annotation is invoked without using the `const` keyword, but all
-of the arguments to the constructor are constants. The annotation indicates
-that the constructor should be used to create a constant value whenever
-possible.
+`[literal][meta-literal]` annotation is invoked without using the `const`
+keyword, but all of the arguments to the constructor are constants. The
+annotation indicates that the constructor should be used to create a
+constant value whenever possible.
 
 #### Example
 
@@ -10743,6 +11576,76 @@
 If the generative constructor is the unnamed constructor, and if there are
 no arguments being passed to it, then you can remove the super invocation.
 
+### non_generative_implicit_constructor
+
+_The unnamed constructor of superclass '{0}' (called by the default constructor
+of '{1}') must be a generative constructor, but factory found._
+
+#### Description
+
+The analyzer produces this diagnostic when a class has an implicit
+generative constructor and the superclass has an explicit unnamed factory
+constructor. The implicit constructor in the subclass implicitly invokes
+the unnamed constructor in the superclass, but generative constructors can
+only invoke another generative constructor, not a factory constructor.
+
+#### Example
+
+The following code produces this diagnostic because the implicit
+constructor in `B` invokes the unnamed constructor in `A`, but the
+constructor in `A` is a factory constructor, when a generative constructor
+is required:
+
+{% prettify dart tag=pre+code %}
+class A {
+  factory A() => throw 0;
+  A.named();
+}
+
+class [!B!] extends A {}
+{% endprettify %}
+
+#### Common fixes
+
+If the unnamed constructor in the superclass can be a generative
+constructor, then change it to be a generative constructor:
+
+{% prettify dart tag=pre+code %}
+class A {
+  A();
+  A.named();
+}
+
+class B extends A { }
+{% endprettify %}
+
+If the unnamed constructor can't be a generative constructor and there are
+other generative constructors in the superclass, then explicitly invoke
+one of them:
+
+{% prettify dart tag=pre+code %}
+class A {
+  factory A() => throw 0;
+  A.named();
+}
+
+class B extends A {
+  B() : super.named();
+}
+{% endprettify %}
+
+If there are no generative constructors that can be used and none can be
+added, then implement the superclass rather than extending it:
+
+{% prettify dart tag=pre+code %}
+class A {
+  factory A() => throw 0;
+  A.named();
+}
+
+class B implements A {}
+{% endprettify %}
+
 ### non_native_function_type_argument_to_pointer
 
 _Can't invoke 'asFunction' because the function signature '{0}' for the pointer
@@ -11525,6 +12428,71 @@
 }
 {% endprettify %}
 
+### no_generative_constructors_in_superclass
+
+_The class '{0}' can't extend '{1}' because '{1}' only has factory constructors
+(no generative constructors), and '{0}' has at least one generative constructor._
+
+#### Description
+
+The analyzer produces this diagnostic when a class that has at least one
+generative constructor (whether explicit or implicit) has a superclass
+that doesn't have any generative constructors. Every generative
+constructor, except the one defined in `Object`, invokes, either
+explicitly or implicitly, one of the generative constructors from its
+superclass.
+
+#### Example
+
+The following code produces this diagnostic because the class `B` has an
+implicit generative constructor that can't invoke a generative constructor
+from `A` because `A` doesn't have any generative constructors:
+
+{% prettify dart tag=pre+code %}
+class A {
+  factory A.none() => throw '';
+}
+
+class B extends [!A!] {}
+{% endprettify %}
+
+#### Common fixes
+
+If the superclass should have a generative constructor, then add one:
+
+{% prettify dart tag=pre+code %}
+class A {
+  A();
+  factory A.none() => throw '';
+}
+
+class B extends A {}
+{% endprettify %}
+
+If the subclass shouldn't have a generative constructor, then remove it by
+adding a factory constructor:
+
+{% prettify dart tag=pre+code %}
+class A {
+  factory A.none() => throw '';
+}
+
+class B extends A {
+  factory B.none() => throw '';
+}
+{% endprettify %}
+
+If the subclass must have a generative constructor but the superclass
+can't have one, then implement the superclass instead:
+
+{% prettify dart tag=pre+code %}
+class A {
+  factory A.none() => throw '';
+}
+
+class B implements A {}
+{% endprettify %}
+
 ### nullable_type_in_catch_clause
 
 _A potentially nullable type can't be used in an 'on' clause because it isn't
@@ -11743,6 +12711,46 @@
 }
 {% endprettify %}
 
+### null_check_always_fails
+
+_This null-check will always throw an exception because the expression will
+always evaluate to 'null'._
+
+#### Description
+
+The analyzer produces this diagnostic when the null check operator (`!`)
+is used on an expression whose value can only be `null`. In such a case
+the operator always throws an exception, which likely isn't the intended
+behavior.
+
+#### Example
+
+The following code produces this diagnostic because the function `g` will
+always return `null`, which means that the null check in `f` will always
+throw:
+
+{% prettify dart tag=pre+code %}
+void f() {
+  [!g()!!];
+}
+
+Null g() => null;
+{% endprettify %}
+
+#### Common fixes
+
+If you intend to always throw an exception, then replace the null check
+with an explicit `throw` expression to make the intent more clear:
+
+{% prettify dart tag=pre+code %}
+void f() {
+  g();
+  throw TypeError();
+}
+
+Null g() => null;
+{% endprettify %}
+
 ### on_repeated
 
 _The type '{0}' can be included in the superclass constraints only once._
@@ -12053,8 +13061,8 @@
 If the library should be using a different file as a part, then change the
 URI in the part directive to be the URI of the other file.
 
-If the part file should be a part of this library, then update the URI (or
-library name) in the part-of directive to be the URI (or name) of the
+If the [part file][] should be a part of this library, then update the URI
+(orlibrary name) in the part-of directive to be the URI (or name) of the
 correct library.
 
 ### part_of_non_part
@@ -12107,21 +13115,22 @@
 #### Description
 
 The analyzer produces this diagnostic when a library that doesn't have a
-`library` directive (and hence has no name) contains a `part` directive and
-the `part of` directive in the part file uses a name to specify the library
-that it's a part of.
+`library` directive (and hence has no name) contains a `part` directive
+and the `part of` directive in the [part file][] uses a name to specify
+the library that it's a part of.
 
 #### Example
 
-Given a part file named `part_file.dart` containing the following code:
+Given a [part file][] named `part_file.dart` containing the following
+code:
 
 {% prettify dart tag=pre+code %}
 part of lib;
 {% endprettify %}
 
 The following code produces this diagnostic because the library including
-the part file doesn't have a name even though the part file uses a name to
-specify which library it's a part of:
+the [part file][] doesn't have a name even though the [part file][] uses a
+name to specify which library it's a part of:
 
 {% prettify dart tag=pre+code %}
 part [!'part_file.dart'!];
@@ -12129,8 +13138,8 @@
 
 #### Common fixes
 
-Change the `part of` directive in the part file to specify its library by
-URI:
+Change the `part of` directive in the [part file][] to specify its library
+by URI:
 
 {% prettify dart tag=pre+code %}
 part of 'test.dart';
@@ -12302,6 +13311,56 @@
 
 If the name is wrong, then correct the name.
 
+### prefix_shadowed_by_local_declaration
+
+_The prefix '{0}' can't be used here because it's shadowed by a local
+declaration._
+
+#### Description
+
+The analyzer produces this diagnostic when an import prefix is used in a
+context where it isn't visible because it was shadowed by a local
+declaration.
+
+#### Example
+
+The following code produces this diagnostic because the prefix `a` is
+being used to access the class `Future`, but isn't visible because it's
+shadowed by the parameter `a`:
+
+{% prettify dart tag=pre+code %}
+import 'dart:async' as a;
+
+a.Future? f(int a) {
+  [!a!].Future? x;
+  return x;
+}
+{% endprettify %}
+
+#### Common fixes
+
+Rename either the prefix:
+
+{% prettify dart tag=pre+code %}
+import 'dart:async' as p;
+
+p.Future? f(int a) {
+  p.Future? x;
+  return x;
+}
+{% endprettify %}
+
+Or rename the local variable:
+
+{% prettify dart tag=pre+code %}
+import 'dart:async' as a;
+
+a.Future? f(int p) {
+  a.Future? x;
+  return x;
+}
+{% endprettify %}
+
 ### private_collision_in_mixin_application
 
 _The private name '{0}', defined by '{1}', conflicts with the same name defined
@@ -12380,6 +13439,91 @@
 }
 {% endprettify %}
 
+### private_setter
+
+_The setter '{0}' is private and can't be accessed outside the library that
+declares it._
+
+#### Description
+
+The analyzer produces this diagnostic when a private setter is used in a
+library where it isn't visible.
+
+#### Example
+
+Given a file named `a.dart` that contains the following:
+
+{% prettify dart tag=pre+code %}
+class A {
+  static int _f = 0;
+}
+{% endprettify %}
+
+The following code produces this diagnostic because it references the
+private setter `_f` even though the setter isn't visible:
+
+{% prettify dart tag=pre+code %}
+import 'a.dart';
+
+void f() {
+  A.[!_f!] = 0;
+}
+{% endprettify %}
+
+#### Common fixes
+
+If you're able to make the setter public, then do so:
+
+{% prettify dart tag=pre+code %}
+class A {
+  static int f = 0;
+}
+{% endprettify %}
+
+If you aren't able to make the setter public, then find a different way to
+implement the code.
+
+### read_potentially_unassigned_final
+
+_The final variable '{0}' can't be read because it's potentially unassigned at
+this point._
+
+#### Description
+
+The analyzer produces this diagnostic when a final local variable that
+isn't initialized at the declaration site is read at a point where the
+compiler can't prove that the variable is always initialized before it's
+referenced.
+
+#### Example
+
+The following code produces this diagnostic because the final local
+variable `x` is read (on line 3) when it's possible that it hasn't yet
+been initialized:
+
+{% prettify dart tag=pre+code %}
+int f() {
+  final int x;
+  return [!x!];
+}
+{% endprettify %}
+
+#### Common fixes
+
+Ensure that the variable has been initialized before it's read:
+
+{% prettify dart tag=pre+code %}
+int f(bool b) {
+  final int x;
+  if (b) {
+    x = 0;
+  } else {
+    x = 1;
+  }
+  return x;
+}
+{% endprettify %}
+
 ### recursive_compile_time_constant
 
 _The compile-time constant expression depends on itself._
@@ -12613,6 +13757,46 @@
 }
 {% endprettify %}
 
+### redirect_to_abstract_class_constructor
+
+_The redirecting constructor '{0}' can't redirect to a constructor of the
+abstract class '{1}'._
+
+#### Description
+
+The analyzer produces this diagnostic when a constructor redirects to a
+constructor in an abstract class.
+
+#### Example
+
+The following code produces this diagnostic because the factory
+constructor in `A` redirects to a constructor in `B`, but `B` is an
+abstract class:
+
+{% prettify dart tag=pre+code %}
+class A {
+  factory A() = [!B!];
+}
+
+abstract class B implements A {}
+{% endprettify %}
+
+#### Common fixes
+
+If the code redirects to the correct constructor, then change the class so
+that it isn't abstract:
+
+{% prettify dart tag=pre+code %}
+class A {
+  factory A() = B;
+}
+
+class B implements A {}
+{% endprettify %}
+
+Otherwise, change the factory constructor so that it either redirects to a
+constructor in a concrete class, or has a concrete implementation.
+
 ### redirect_to_invalid_function_type
 
 _The redirected constructor '{0}' has incompatible parameters with '{1}'._
@@ -12739,6 +13923,58 @@
 }
 {% endprettify %}
 
+### redirect_to_missing_constructor
+
+_The constructor '{0}' couldn't be found in '{1}'._
+
+#### Description
+
+The analyzer produces this diagnostic when a constructor redirects to a
+constructor that doesn't exist.
+
+#### Example
+
+The following code produces this diagnostic because the factory
+constructor in `A` redirects to a constructor in `B` that doesn't exist:
+
+{% prettify dart tag=pre+code %}
+class A {
+  factory A() = [!B.name!];
+}
+
+class B implements A {
+  B();
+}
+{% endprettify %}
+
+#### Common fixes
+
+If the constructor being redirected to is correct, then define the
+constructor:
+
+{% prettify dart tag=pre+code %}
+class A {
+  factory A() = B.name;
+}
+
+class B implements A {
+  B();
+  B.name();
+}
+{% endprettify %}
+
+If a different constructor should be invoked, then update the redirect:
+
+{% prettify dart tag=pre+code %}
+class A {
+  factory A() = B;
+}
+
+class B implements A {
+  B();
+}
+{% endprettify %}
+
 ### redirect_to_non_class
 
 _The name '{0}' isn't a type and can't be used in a redirected constructor._
@@ -13071,6 +14307,58 @@
 }
 {% endprettify %}
 
+### return_of_do_not_store
+
+_'{0}' is annotated with 'doNotStore' and shouldn't be returned unless '{1}' is
+also annotated._
+
+#### Description
+
+The analyzer produces this diagnostic when a value that is annotated with
+the `[doNotStore][meta-doNotStore]` annotation is returned from a method,
+getter, or function that doesn't have the same annotation.
+
+#### Example
+
+The following code produces this diagnostic because the result of invoking
+`f` shouldn't be stored, but the function `g` isn't annotated to preserve
+that semantic:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+@doNotStore
+int f() => 0;
+
+int g() => [!f()!];
+{% endprettify %}
+
+#### Common fixes
+
+If the value that shouldn't be stored is the correct value to return, then
+mark the function with the `[doNotStore][meta-doNotStore]` annotation:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+@doNotStore
+int f() => 0;
+
+@doNotStore
+int g() => f();
+{% endprettify %}
+
+Otherwise, return a different value from the function:
+
+{% prettify dart tag=pre+code %}
+import 'package:meta/meta.dart';
+
+@doNotStore
+int f() => 0;
+
+int g() => 0;
+{% endprettify %}
+
 ### return_of_invalid_type
 
 _A value of type '{0}' can't be returned from the constructor '{2}' because it
@@ -14135,10 +15423,10 @@
 #### Description
 
 The analyzer produces this diagnostic when a sealed class (one that either
-has the `@sealed` annotation or inherits or mixes in a sealed class) is
-referenced in either the `extends`, `implements`, or `with` clause of a
-class or mixin declaration if the declaration isn't in the same package as
-the sealed class.
+has the `[sealed][meta-sealed]` annotation or inherits or mixes in a
+sealed class) is referenced in either the `extends`, `implements`, or
+`with` clause of a class or mixin declaration if the declaration isn't in
+the same package as the sealed class.
 
 #### Example
 
@@ -14405,6 +15693,43 @@
 }
 {% endprettify %}
 
+### switch_case_completes_normally
+
+_The 'case' shouldn't complete normally._
+
+#### Description
+
+The analyzer produces this diagnostic when the statements following a
+`case` label in a `switch` statement could fall through to the next `case`
+or `default` label.
+
+#### Example
+
+The following code produces this diagnostic because the `case` label with
+ a value of zero (`0`) falls through to the `default` statements:
+
+{% prettify dart tag=pre+code %}
+void f(int a) {
+  switch (a) {
+    [!case!] 0:
+      print(0);
+    default:
+      return;
+  }
+}
+{% endprettify %}
+
+#### Common fixes
+
+Change the flow of control so that the `case` won't fall through. There
+are several ways that this can be done, including adding one of the
+following at the end of the current list of statements:
+- a `return` statement,
+- a `throw` expression,
+- a `break` statement,
+- a `continue`, or
+- an invocation of a function or method whose return type is `Never`.
+
 ### switch_expression_not_assignable
 
 _Type '{0}' of the switch expression isn't assignable to the type '{1}' of case
@@ -15879,8 +17204,8 @@
 #### Description
 
 The analyzer produces this diagnostic when an annotation of the form
-`@UnusedResult.unless(parameterDefined: parameterName)` specifies a
-parameter name that isn't defined by the annotated function.
+`[UseResult][meta-UseResult].unless(parameterDefined: parameterName)`
+specifies a parameter name that isn't defined by the annotated function.
 
 #### Example
 
@@ -16720,16 +18045,16 @@
 #### Description
 
 The analyzer produces this diagnostic when a function annotated with
-`useResult` is invoked, and the value returned by that function isn't used.
-The value is considered to be used if a member of the value is invoked, if
-the value is passed to another function, or if the value is assigned to a
-variable or field.
+`[useResult][meta-useResult]` is invoked, and the value returned by that
+function isn't used. The value is considered to be used if a member of the
+value is invoked, if the value is passed to another function, or if the
+value is assigned to a variable or field.
 
 #### Example
 
 The following code produces this diagnostic because the invocation of
 `c.a()` isn't used, even though the method `a` is annotated with
-`useResult`:
+`[useResult][meta-useResult]`:
 
 {% prettify dart tag=pre+code %}
 import 'package:meta/meta.dart';
diff --git a/pkg/analyzer/tool/diagnostics/generate.dart b/pkg/analyzer/tool/diagnostics/generate.dart
index 9f58663..f326cd70 100644
--- a/pkg/analyzer/tool/diagnostics/generate.dart
+++ b/pkg/analyzer/tool/diagnostics/generate.dart
@@ -191,6 +191,19 @@
 The analyzer produces the following diagnostics for code that
 doesn't conform to the language specification or
 that might work in unexpected ways.
+
+[meta-doNotStore]: https://pub.dev/documentation/meta/latest/meta/doNotStore-constant.html
+[meta-factory]: https://pub.dev/documentation/meta/latest/meta/factory-constant.html
+[meta-immutable]: https://pub.dev/documentation/meta/latest/meta/immutable-constant.html
+[meta-internal]: https://pub.dev/documentation/meta/latest/meta/internal-constant.html
+[meta-literal]: https://pub.dev/documentation/meta/latest/meta/literal-constant.html
+[meta-mustCallSuper]: https://pub.dev/documentation/meta/latest/meta/mustCallSuper-constant.html
+[meta-optionalTypeArgs]: https://pub.dev/documentation/meta/latest/meta/optionalTypeArgs-constant.html
+[meta-sealed]: https://pub.dev/documentation/meta/latest/meta/sealed-constant.html
+[meta-useResult]: https://pub.dev/documentation/meta/latest/meta/useResult-constant.html
+[meta-UseResult]: https://pub.dev/documentation/meta/latest/meta/UseResult-class.html
+[meta-visibleForOverriding]: https://pub.dev/documentation/meta/latest/meta/visibleForOverriding-constant.html
+[meta-visibleForTesting]: https://pub.dev/documentation/meta/latest/meta/visibleForTesting-constant.html
 ''');
     List<String> errorCodes = infoByName.keys.toList();
     errorCodes.sort();
@@ -215,13 +228,17 @@
 * [definite assignment][]
 * [mixin application][]
 * [override inference][]
+* [part file][]
 * [potentially non-nullable][]
+* [public library][]
 
 [constant context]: #constant-context
 [definite assignment]: #definite-assignment
 [mixin application]: #mixin-application
 [override inference]: #override-inference
+[part file]: #part-file
 [potentially non-nullable]: #potentially-non-nullable
+[public library]: #public-library
 
 ### Constant context
 
@@ -442,6 +459,10 @@
 It is an error if none of the overridden methods has a function type that is a
 supertype of all the other overridden methods.
 
+### Part file
+
+A part file is a Dart source file that contains a `part of` directive.
+
 ### Potentially non-nullable
 
 A type is _potentially non-nullable_ if it's either explicitly non-nullable or
@@ -457,6 +478,11 @@
 (the type specified as a type argument) might be non-nullable. For example,
 given a declaration of `class C<T> {}`, the type `C` could be used with a
 non-nullable type argument as in `C<int>`.
+
+### Public library
+
+A public library is a library that is located inside the package's `lib`
+directory but not inside the `lib/src` directory.
 ''');
   }
 
diff --git a/tools/VERSION b/tools/VERSION
index dfc959b..d3ae75a 100644
--- a/tools/VERSION
+++ b/tools/VERSION
@@ -27,5 +27,5 @@
 MAJOR 2
 MINOR 17
 PATCH 0
-PRERELEASE 150
+PRERELEASE 151
 PRERELEASE_PATCH 0
\ No newline at end of file