falconGitHub

provide-deprecation-message

Same as provide_deprecation_message in Dart lints

Group
Style
Path
lint/style/provide-deprecation-message
Default
On (recommended)
Origin
Dart lints
Rule
426 of 512
recommended

Flags @deprecated and @Deprecated() annotations that carry no message.

A deprecation is only useful if it tells callers what to do instead — which replacement to adopt, or since when the API is going away. The bare @deprecated constant can never carry that guidance, and @Deprecated() with no argument (or an empty/whitespace-only string) is just as unhelpful, so both should be replaced with @Deprecated("message"). A @Deprecated whose positional argument is any non-empty expression is accepted. The rule also inspects field-level annotations, which the generic syntax-tree walk would otherwise skip.

Invalid

example.dartdart
class Api {
  @deprecated
  void oldMethod() {}

  @Deprecated('')
  void emptyMessage() {}

  @Deprecated('   ')
  void whitespaceMessage() {}

  @deprecated
  int oldField = 0;
}

@deprecated
void oldTopLevel() {}

class MultiField {
  // The annotation belongs to the declaration, so one diagnostic covers both.
  @deprecated
  int a = 0, b = 1;
}
Provide a deprecation message via `@Deprecated("message")`.
1class Api {
2 @deprecated
Provide a deprecation message via `@Deprecated("message")`.
4
5 @Deprecated('')
Provide a deprecation message via `@Deprecated("message")`.
7
8 @Deprecated(' ')
Provide a deprecation message via `@Deprecated("message")`.
10
11 @deprecated
Provide a deprecation message via `@Deprecated("message")`.
14
15@deprecated
Provide a deprecation message via `@Deprecated("message")`.
19 // The annotation belongs to the declaration, so one diagnostic covers both.
20 @deprecated

Valid

example.dartdart
class Api {
  @Deprecated('Use newMethod instead.')
  void oldMethod() {}

  @Deprecated('Removed in version 2.0.')
  int oldField = 0;

  @override
  String toString() => 'Api';
}

@Deprecated('No longer supported; use Service.')
void oldTopLevel() {}

@Deprecated('Use the replacement class.')
class OldClass {}

Configure provide-deprecation-message

Set its severity in falcon.json. See the configuration guide.

falcon.jsonjson
{
  "linter": {
    "rules": {
      "style": {
        "provide-deprecation-message": "error"
      }
    }
  }
}

Or silence one occurrence with a suppression comment; the reason is required.

example.dartdart
// falcon-ignore lint/style/provide-deprecation-message: <reason>