Allow rejecting normally valid tag names and/or providing custom error messages when suggesting tags to reject or replace (#302)

* feat(check-tag-names): allow rejecting normally valid tag names and/or providing custom error messages when suggesting tags to reject or replace (fixes #108)

Reporting normally valid tags may be of interest for tags like `@todo`. This is implemented by allowing the user to set targeted `tagNamePreference` tags to `false` or to an object with only a `message` and no `replacement`

Custom messages for `check-tag-names` are implemented by allowing the user to set  targeted `tagNamePreference` tags to an object with `message` and `replacement` (mirroring `preferredTypes` behavior). Note that for other rules leveraging `tagNamePreference` (via `utils.getPreferredTagName`) to find the user's preferred tag name, the `replacement` will be used in the likes of error messages but not the `message`.

Also, for various (param, return, and description-related) rules which have used `tagNamePreference` (via the `utils.getPreferredTagName` utility), report to user if they have blocked (probably inadvertently) and not indicated a replacement for the relevant tag needed by the rule in the `tagNamePreference` setting.

Also, ensure `require-param-name` and `check-examples` report preferred tag name (not necessarily `param` or `example`, respectively) and err if `example` is a rejected tag

Author: brettz9

.README/README.md

@@ -147,6 +147,59 @@ Use `settings.jsdoc.tagNamePreference` to configure a preferred alias name for a
 }
 ```
 
+One may also use an object with a `message` and `replacement`.
+
+The following will report the message `@extends is to be used over @augments as it is more evocative of classes than @augments` upon encountering `@augments`.
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "augments": {
+                  "message": "@extends is to be used over @augments as it is more evocative of classes than @augments",
+                  "replacement": "extends"
+                }
+            }
+        }
+    }
+}
+```
+
+If one wishes to reject a normally valid tag, e.g., `@todo`, one may set the tag to `false`:
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "todo": false
+            }
+        }
+    }
+}
+```
+
+Or one may set the targeted tag to an object with a custom `message`, but without a `replacement` property:
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "todo": {
+                  "message": "We expect immediate perfection, so don't leave to-dos in your code."
+                }
+            }
+        }
+    }
+}
+```
+
+
 The defaults in `eslint-plugin-jsdoc` (for tags which offer
 aliases) are as follows:
 

README.md

@@ -197,6 +197,59 @@ Use `settings.jsdoc.tagNamePreference` to configure a preferred alias name for a
 }
 ```
 
+One may also use an object with a `message` and `replacement`.
+
+The following will report the message `@extends is to be used over @augments as it is more evocative of classes than @augments` upon encountering `@augments`.
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "augments": {
+                  "message": "@extends is to be used over @augments as it is more evocative of classes than @augments",
+                  "replacement": "extends"
+                }
+            }
+        }
+    }
+}
+```
+
+If one wishes to reject a normally valid tag, e.g., `@todo`, one may set the tag to `false`:
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "todo": false
+            }
+        }
+    }
+}
+```
+
+Or one may set the targeted tag to an object with a custom `message`, but without a `replacement` property:
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "todo": {
+                  "message": "We expect immediate perfection, so don't leave to-dos in your code."
+                }
+            }
+        }
+    }
+}
+```
+
+
 The defaults in `eslint-plugin-jsdoc` (for tags which offer
 aliases) are as follows:
 
@@ -956,6 +1009,15 @@ export class SomeClass {
   constructor(private property: string) {}
 }
 // Message: Expected @param names to be "property". Got "prop".
+
+/**
+ * @param foo
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"param":false}}}
+// Message: Unexpected tag `@param`
 ````
 
 The following patterns are not considered problems:
@@ -1277,6 +1339,42 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}
 // Message: Invalid JSDoc tag name "baz".
+
+/**
+ * @todo
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"todo":false}}}
+// Message: Blacklisted tag found (`@todo`)
+
+/**
+ * @todo
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"todo":{"message":"Please resolve to-dos or add to the tracker"}}}}
+// Message: Please resolve to-dos or add to the tracker
+
+/**
+ * @todo
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"todo":{"message":"Please use x-todo instead of todo","replacement":"x-todo"}}}}
+// Message: Please use x-todo instead of todo
+
+/**
+ * @todo
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"todo":{"message":"Please use x-todo instead of todo","replacement":"x-todo"}}}}
+// Message: Please use x-todo instead of todo
 ````
 
 The following patterns are not considered problems:
@@ -1392,6 +1490,13 @@ function quux (foo) {}
  */
 function quux (foo) {
 
+}
+
+/**
+ * @todo
+ */
+function quux () {
+
 }
 ````
 
@@ -3656,6 +3761,24 @@ var quux = {
 };
 // Options: [{"contexts":["ObjectExpression"]}]
 // Message: Missing JSDoc @description declaration.
+
+/**
+ * @someDesc
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"description":{"message":"Please avoid `{{tagName}}`; use `{{replacement}}` instead","replacement":"someDesc"}}}}
+// Message: Missing JSDoc @someDesc description.
+
+/**
+ * @description
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"description":false}}}
+// Message: Unexpected tag `@description`
 ````
 
 The following patterns are not considered problems:
@@ -3934,6 +4057,15 @@ function quux () {
 }
 // Options: ["always"]
 // Message: There must be a hyphen before @param description.
+
+/**
+ * @param foo
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"param":false}}}
+// Message: Unexpected tag `@param`
 ````
 
 The following patterns are not considered problems:
@@ -4848,6 +4980,15 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
 // Message: Missing JSDoc @arg "foo" description.
+
+/**
+ * @param foo
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"param":false}}}
+// Message: Unexpected tag `@param`
 ````
 
 The following patterns are not considered problems:
@@ -4902,6 +5043,15 @@ function quux (foo) {
 
 }
 // Message: There must be an identifier after @param tag.
+
+/**
+ * @param foo
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"param":false}}}
+// Message: Unexpected tag `@param`
 ````
 
 The following patterns are not considered problems:
@@ -4953,6 +5103,15 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
 // Message: Missing JSDoc @arg "foo" type.
+
+/**
+ * @param foo
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"param":false}}}
+// Message: Unexpected tag `@param`
 ````
 
 The following patterns are not considered problems:
@@ -5118,6 +5277,15 @@ export class SomeClass {
   constructor(private property: string, private foo: number) {}
 }
 // Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ *
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"param":false}}}
+// Message: Unexpected tag `@param`
 ````
 
 The following patterns are not considered problems:
@@ -5499,6 +5667,15 @@ class Foo {
   }
 }
 // Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ * @returns
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"returns":false}}}
+// Message: Unexpected tag `@returns`
 ````
 
 The following patterns are not considered problems:
@@ -5778,6 +5955,15 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
 // Message: Missing JSDoc @return description.
+
+/**
+ * @returns
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"returns":false}}}
+// Message: Unexpected tag `@returns`
 ````
 
 The following patterns are not considered problems:
@@ -5851,6 +6037,15 @@ function quux () {
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
 // Message: Missing JSDoc @return type.
+
+/**
+ * @returns
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"returns":false}}}
+// Message: Unexpected tag `@returns`
 ````
 
 The following patterns are not considered problems:
@@ -5995,6 +6190,15 @@ function quux (foo) {
   return foo;
 }
 // Message: Found more than one @returns declaration.
+
+/**
+ * @returns
+ */
+function quux () {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"returns":false}}}
+// Message: Unexpected tag `@returns`
 ````
 
 The following patterns are not considered problems:

package.json

@@ -24,6 +24,7 @@
     "babel-plugin-add-module-exports": "^1.0.2",
     "babel-plugin-istanbul": "^5.1.4",
     "chai": "^4.2.0",
+    "escape-regex-string": "^1.0.6",
     "eslint": "^6.0.1",
     "eslint-config-canonical": "^17.1.1",
     "gitdown": "^2.6.1",