rspec/rules/S1123/dart/rule.adoc

== Why is this an issue?

Deprecation should be marked with both the ``++@Deprecated++`` annotation. This annotation triggers compiler to produce a warning, when the deprecated element is used. It also enables tools such as IDEs to warn about referencing deprecated elements. When using this annotation, it is important to add a message to the deprecation to explain when it was deprecated, why, and how references should be refactored.


=== Noncompliant code example

[source, dart]
----
@deprecated
void oldFunction(arg1, arg2) {}
----


=== Compliant solution

[source, dart]
----
@Deprecated("""
[oldFunction] is being deprecated in favor of [newFunction] (with slightly
different parameters; see [newFunction] for more information). [oldFunction]
will be removed on or after the 4.0.0 release.
""")
void oldFunction(arg1, arg2) {}
----

== Resources

* https://dart.dev/tools/linter-rules/provide_deprecation_message[Dart Lint rule]