Linter: provide a lint if a `@deprecated` annotation has no description of the deprecation

[devoncarew]

It's useful when deprecating functionality to indicate to the user what the recommended alternative is. So, instead of:

@deprecated
void foo() {
  ...
}

we should prefer:

@Deprecated('Prefer to use the bar() method')
void foo() {
  ...
}

/cc @kevmoo

[bwilkerson]

It's useful when deprecating functionality to indicate to the user what the recommended alternative is.

That's true, but that's not what the optional argument is used for:

  /**
   * Create a deprecation annotation which specifies the expiration of the
   * annotated feature.
   *
   * The [expires] argument should be readable by programmers, and should state
   * when an annotated feature is expected to be removed.
   * This can be specified, for example, as a date, as a release number, or
   * as relative to some other change (like "when bug 4418 is fixed").
   */
  const Deprecated(String expires) : this.expires = expires;

[devoncarew]

I've never seen it used for that purpose. We'd probably gather good info by surveying existing code, but generally, I don't think we should be limited by what that dartdoc comment says.

[pq]

It sounds like we should update the docs regardless?

[kevmoo]

We could always deprecate @deprecate 😄

[srawlins]

Okie doke, at some point, the description of the Deprecated constructor argument changed to this:

Create a deprecation annotation which specifies the migration path and expiration of the annotated feature.

The message argument should be readable by programmers, and should state an alternative feature (if available) as well as when an annotated feature is expected to be removed.

At this point, I think the original lint request is perfectly valid :)