add deprecated annotation to documentation (fixes #295)

README.md

@@ -241,8 +241,8 @@ These rules help you to enforce the usage of angular wrappers.
 
 These rules will be removed in version 1.0.0
 
- * [no-digest](docs/no-digest.md) - DEPRECATED! use `$apply()` instead of `$digest()` (replaced by [watchers-execution](docs/watchers-execution.md))
- * [typecheck-regexp](docs/typecheck-regexp.md) - DEPRECATED! use `angular.isRegexp` instead of other comparisons (no native angular method)
+ * [no-digest](docs/no-digest.md) - use `$apply()` instead of `$digest()` (replaced by [watchers-execution](docs/watchers-execution.md))
+ * [typecheck-regexp](docs/typecheck-regexp.md) - use `angular.isRegexp` instead of other comparisons (no native angular method)
 
 
 ----

docs/no-digest.md

@@ -2,9 +2,13 @@
 
 # no-digest - use `$apply()` instead of `$digest()`
 
-DEPRECATED! The scope's $digest() method shouldn't be used.
+**This rule is deprecated and will be removed in future versions. Explanation: There is no reason to forbid the use of `$digest()` in general.**
+
+The scope's $digest() method shouldn't be used.
 You should prefer the $apply method.
 
+The `watchers-execution` rule can be configured to enforce the use of `$apply()` or `$digest()`.
+
 ## Version
 
 This rule was introduced in eslint-plugin-angular 0.1.0

docs/typecheck-regexp.md

@@ -2,7 +2,9 @@
 
 # typecheck-regexp - use `angular.isRegexp` instead of other comparisons
 
-DEPRECATED! You should use the angular.isRegexp method instead of the default JavaScript implementation (toString.call(/^A/) === "[object RegExp]").
+**This rule is deprecated and will be removed in future versions. Explanation: `angular.isRegexp` is no built-in angular method.**
+
+You should use the angular.isRegexp method instead of the default JavaScript implementation (toString.call(/^A/) === "[object RegExp]").
 
 ## Version
 

rules/no-digest.js

@@ -1,12 +1,14 @@
 /**
  * use `$apply()` instead of `$digest()`
  *
- * DEPRECATED! The scope's $digest() method shouldn't be used.
+ * The scope's $digest() method shouldn't be used.
  * You should prefer the $apply method.
  *
- * @linkDescription DEPRECATED! use `$apply()` instead of `$digest()` (replaced by [watchers-execution](docs/watchers-execution.md))
+ * The `watchers-execution` rule can be configured to enforce the use of `$apply()` or `$digest()`.
+ *
+ * @linkDescription use `$apply()` instead of `$digest()` (replaced by [watchers-execution](docs/watchers-execution.md))
  * @version 0.1.0
- * @category deprecatedRule
+ * @deprecated There is no reason to forbid the use of `$digest()` in general.
  */
 'use strict';
 

rules/typecheck-regexp.js

@@ -1,11 +1,11 @@
 /**
  * use `angular.isRegexp` instead of other comparisons
  *
- * DEPRECATED! You should use the angular.isRegexp method instead of the default JavaScript implementation (toString.call(/^A/) === "[object RegExp]").
+ * You should use the angular.isRegexp method instead of the default JavaScript implementation (toString.call(/^A/) === "[object RegExp]").
  *
- * @linkDescription DEPRECATED! use `angular.isRegexp` instead of other comparisons (no native angular method)
+ * @linkDescription use `angular.isRegexp` instead of other comparisons (no native angular method)
  * @version 0.1.0
- * @category deprecatedRule
+ * @deprecated `angular.isRegexp` is no built-in angular method.
  */
 'use strict';
 

scripts/docs.js

@@ -187,6 +187,13 @@ function _createRule(ruleName) {
     rule.version = mainRuleComment.version;
     rule.category = mainRuleComment.category || 'uncategorizedRule';
 
+    rule.deprecated = !!mainRuleComment.deprecated;
+
+    if (rule.deprecated) {
+        rule.deprecationReason = mainRuleComment.deprecated;
+        rule.category = 'deprecatedRule';
+    }
+
     if (!rule.version) {
         throw new Error('No @version found for ' + ruleName);
     }

scripts/templates/ruleDocumentationContent.template.md

@@ -2,6 +2,10 @@
 
 # <%= ruleName %> - <%= lead %>
 
+<% if(deprecated) { %>
+**This rule is deprecated and will be removed in future versions. Explanation: <%= deprecationReason %>**
+<% } %>
+
 <%= description %>
 
 <% if(styleguideReferences.length > 0) { %>