Version 2.17.0-151.0.dev
Merge commit '2f9d45b8bf9e5843acb94996e193e1a6fdf2da8b' into 'dev'
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
