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

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

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Missing a deprecation message.

=== Highlighting

The annotation, including the `@` symbol.

'''
== Comments And Links
(visible only on this page)

include::../comments-and-links.adoc[]

endif::env-github,rspecator-view[]