Misleading deprecation notices - rule deprecation vs. angular feature deprecation

[tilmanschweitzer]

The DEPRECATED! information in the rule overview can be interpreted as deprecation of the rule itself (correct) or as information that an angular feature is deprecated (wrong).

Example from an Issue (#294):

• no-digest - DEPRECATED! use $apply() instead of $digest() (replaced by watchers-execution)

[EmmanuelDemey]

It's quiet difficult to find a better term. We always use DEPRECATED for our own API, and not for an external framework's API. Maybe change to "RULE DEPRECATED" ?
What do you think ?

[remcohaszing]

Why not use the standard jsdoc tag @deprecated for deprecation of rules? (It even gets highlighted in several editors.)

/**
 * use `$apply()` instead of `$digest()`
 *
 * The scope's $digest() method shouldn't be used.
 * You should prefer the $apply method.
 *
 * @linkDescription Use `$apply()` instead of `$digest()` (replaced by [watchers-execution](docs/watchers-execution.md))
 * @version 0.1.0
 * @deprecated because of reasons
 */

For rendering the readme the deprecation could be rendered before the hyphen, so it's obviously not part of the description

* [no-digest](docs/no-digest.md) (**DEPRECATED**) - Use `$apply()` instead of `$digest()` (replaced by [watchers-execution](docs/watchers-execution.md))

The generated docs could then contain a section separately from the actual description of the rule stating why the rule is deprecated.

<!-- WARNING: Generated documentation. Edit docs and examples in the rule and examples file ('rules/no-digest.js', 'examples/no-digest.js'). -->

# no-digest - use `$apply()` instead of `$digest()`

**This rule is deprecated because of reasons**

The scope's $digest() method shouldn't be used.
You should prefer the $apply method.

## Version

This rule was introduced in eslint-plugin-angular 0.1.0

## Links

* [Rule source](../rules/no-digest.js)
* [Example source](../examples/no-digest.js)

[tilmanschweitzer]

+1 for @depcrecated

... and I also think RULE DEPRECATED could help.

Another additional idea is to list the deprecated rules separate from the others.

[remcohaszing]

Another additional idea is to list the deprecated rules separate from the others.

👍

Perhaps also a note on when deprecated rules will be removed. (I'd say all currently deprecated rules should be removed in 1.0.0.)

[tilmanschweitzer]

Removing the typecheck-regexp rule is already scheduled for 1.0.0. I'll add an issue for all deprecated rules.

[tilmanschweitzer]

I would like to group all rules in categories and opened an issue with a proposal for these categories.

#297