feat(check-tag-names): auto-allow tags in tagNamePreference setting to be defined; add definedTags option to replace additionalTagNames.customTags setting

BREAKING CHANGE:

Switch `additionalTagNames.customTags` setting to `definedTags` option (only used by one rule)

Author: brettz9

.README/README.md

@@ -199,6 +199,8 @@ Or one may set the targeted tag to an object with a custom `message`, but withou
 }
 ```
 
+Note that the preferred tags indicated in the `settings.jsdoc.tagNamePreference`
+map will be assumed to be defined by `check-tag-names`.
 
 The defaults in `eslint-plugin-jsdoc` (for tags which offer
 aliases) are as follows:
@@ -236,24 +238,6 @@ This setting is utilized by the the rule for tag name checking
 - `require-returns-description`
 - `require-returns-type`
 
-### Additional Tag Names
-
-Use `settings.jsdoc.additionalTagNames` to configure additional, allowed JSDoc
-tags in the rule `check-tag-names`. The format of the configuration is as follows:
-
-```json
-{
-    "rules": {},
-    "settings": {
-        "jsdoc": {
-            "additionalTagNames": {
-                "customTags": ["define", "record"]
-            }
-        }
-    }
-}
-```
-
 ### `@override`/`@augments`/`@extends`/`@implements` Without Accompanying `@param`/`@description`/`@example`/`@returns`
 
 The following settings allows the element(s) they reference to be omitted

.README/rules/check-tag-names.md

@@ -75,10 +75,26 @@ version
 yields
 ```
 
+Note that the tags indicated as replacements in `settings.jsdoc.tagNamePreference` will automatically be considered as valid.
+
+#### Options
+
+##### `definedTags`
+
+Use an array of `definedTags` strings to configure additional, allowed JSDoc tags.
+The format is as follows:
+
+```json
+{
+  "definedTags": ["define", "record"]
+}
+```
+
 |||
 |---|---|
 |Context|everywhere|
 |Tags|N/A|
-|Settings|`tagNamePreference`, `additionalTagNames`|
+|Options|`definedTags`|
+|Settings|`tagNamePreference`|
 
 <!-- assertions checkTagNames -->

README.md

@@ -16,7 +16,6 @@ JSDoc linting rules for ESLint.
         * [Allow `@private` to disable rules for that comment block](#eslint-plugin-jsdoc-settings-allow-private-to-disable-rules-for-that-comment-block)
         * [Exempting empty functions from `require-jsdoc`](#eslint-plugin-jsdoc-settings-exempting-empty-functions-from-require-jsdoc)
         * [Alias Preference](#eslint-plugin-jsdoc-settings-alias-preference)
-        * [Additional Tag Names](#eslint-plugin-jsdoc-settings-additional-tag-names)
         * [`@override`/`@augments`/`@extends`/`@implements` Without Accompanying `@param`/`@description`/`@example`/`@returns`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns)
         * [Settings to Configure `check-types` and `no-undefined-types`](#eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types)
         * [Settings to Configure `valid-types`](#eslint-plugin-jsdoc-settings-settings-to-configure-valid-types)
@@ -249,6 +248,8 @@ Or one may set the targeted tag to an object with a custom `message`, but withou
 }
 ```
 
+Note that the preferred tags indicated in the `settings.jsdoc.tagNamePreference`
+map will be assumed to be defined by `check-tag-names`.
 
 The defaults in `eslint-plugin-jsdoc` (for tags which offer
 aliases) are as follows:
@@ -286,25 +287,6 @@ This setting is utilized by the the rule for tag name checking
 - `require-returns-description`
 - `require-returns-type`
 
-<a name="eslint-plugin-jsdoc-settings-additional-tag-names"></a>
-### Additional Tag Names
-
-Use `settings.jsdoc.additionalTagNames` to configure additional, allowed JSDoc
-tags in the rule `check-tag-names`. The format of the configuration is as follows:
-
-```json
-{
-    "rules": {},
-    "settings": {
-        "jsdoc": {
-            "additionalTagNames": {
-                "customTags": ["define", "record"]
-            }
-        }
-    }
-}
-```
-
 <a name="eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns"></a>
 ### <code>@override</code>/<code>@augments</code>/<code>@extends</code>/<code>@implements</code> Without Accompanying <code>@param</code>/<code>@description</code>/<code>@example</code>/<code>@returns</code>
 
@@ -1249,11 +1231,29 @@ version
 yields
 ```
 
+Note that the tags indicated as replacements in `settings.jsdoc.tagNamePreference` will automatically be considered as valid.
+
+<a name="eslint-plugin-jsdoc-rules-check-tag-names-options"></a>
+#### Options
+
+<a name="eslint-plugin-jsdoc-rules-check-tag-names-options-definedtags"></a>
+##### <code>definedTags</code>
+
+Use an array of `definedTags` strings to configure additional, allowed JSDoc tags.
+The format is as follows:
+
+```json
+{
+  "definedTags": ["define", "record"]
+}
+```
+
 |||
 |---|---|
 |Context|everywhere|
 |Tags|N/A|
-|Settings|`tagNamePreference`, `additionalTagNames`|
+|Options|`definedTags`|
+|Settings|`tagNamePreference`|
 
 The following patterns are considered problems:
 
@@ -1327,7 +1327,7 @@ function quux (foo) {
 function quux (foo) {
 
 }
-// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}
+// Options: [{"definedTags":["bar"]}]
 // Message: Invalid JSDoc tag name "baz".
 
 /**
@@ -1337,7 +1337,7 @@ function quux (foo) {
 function quux (foo) {
 
 }
-// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}
+// Options: [{"definedTags":["bar"]}]
 // Message: Invalid JSDoc tag name "baz".
 
 /**
@@ -1375,6 +1375,15 @@ 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":55}}}
+// Message: Invalid `settings.jsdoc.tagNamePreference`. Values must be falsy, a string, or an object.
 ````
 
 The following patterns are not considered problems:
@@ -1408,15 +1417,23 @@ function quux (foo) {
 function quux (foo) {
 
 }
-// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["bar"]}}}
+// Options: [{"definedTags":["bar"]}]
+
+/**
+ * @baz @bar foo
+ */
+function quux (foo) {
+
+}
+// Options: [{"definedTags":["baz","bar"]}]
 
 /**
  * @baz @bar foo
  */
 function quux (foo) {
 
 }
-// Settings: {"jsdoc":{"additionalTagNames":{"customTags":["baz","bar"]}}}
+// Settings: {"jsdoc":{"tagNamePreference":{"param":"baz","returns":{"message":"Prefer `bar`","replacement":"bar"},"todo":false}}}
 
 /** 
  * @abstract
@@ -1521,7 +1538,7 @@ Date
 RegExp
 ```
 
-<a name="eslint-plugin-jsdoc-rules-check-types-options"></a>
+<a name="eslint-plugin-jsdoc-rules-check-types-options-1"></a>
 #### Options
 
 `check-types` allows one option:
@@ -2402,10 +2419,10 @@ by our supported Node versions):
 
 ``^([A-Z]|[`\\d_])[\\s\\S]*[.?!`]$``
 
-<a name="eslint-plugin-jsdoc-rules-match-description-options-1"></a>
+<a name="eslint-plugin-jsdoc-rules-match-description-options-2"></a>
 #### Options
 
-<a name="eslint-plugin-jsdoc-rules-match-description-options-1-matchdescription"></a>
+<a name="eslint-plugin-jsdoc-rules-match-description-options-2-matchdescription"></a>
 ##### <code>matchDescription</code>
 
 You can supply your own expression to override the default, passing a
@@ -2420,7 +2437,7 @@ You can supply your own expression to override the default, passing a
 As with the default, the supplied regular expression will be applied with the
 Unicode (`"u"`) flag and is *not* case-insensitive.
 
-<a name="eslint-plugin-jsdoc-rules-match-description-options-1-tags"></a>
+<a name="eslint-plugin-jsdoc-rules-match-description-options-2-tags"></a>
 ##### <code>tags</code>
 
 If you want different regular expressions to apply to tags, you may use
@@ -2447,7 +2464,7 @@ tag should be linted with the `matchDescription` value (or the default).
 }
 ```
 
-<a name="eslint-plugin-jsdoc-rules-match-description-options-1-maindescription"></a>
+<a name="eslint-plugin-jsdoc-rules-match-description-options-2-maindescription"></a>
 ##### <code>mainDescription</code>
 
 If you wish to override the main function description without changing the
@@ -2469,7 +2486,7 @@ There is no need to add `mainDescription: true`, as by default, the main
 function (and only the main function) is linted, though you may disable checking
 it by setting it to `false`.
 
-<a name="eslint-plugin-jsdoc-rules-match-description-options-1-contexts"></a>
+<a name="eslint-plugin-jsdoc-rules-match-description-options-2-contexts"></a>
 ##### <code>contexts</code>
 
 Set this to an array of strings representing the AST context
@@ -2915,7 +2932,7 @@ const q = {
 
 Enforces a consistent padding of the block description.
 
-<a name="eslint-plugin-jsdoc-rules-newline-after-description-options-2"></a>
+<a name="eslint-plugin-jsdoc-rules-newline-after-description-options-3"></a>
 #### Options
 
 This rule allows one optional string argument. If it is `"always"` then a problem is raised when there is a newline after the description. If it is `"never"` then a problem is raised when there is no newline after the description. The default value is `"always"`.
@@ -3075,7 +3092,7 @@ The following types are always considered defined.
 - `any`, `*`
 - `Array`, `Object`, `RegExp`, `Date`, `Function`
 
-<a name="eslint-plugin-jsdoc-rules-no-undefined-types-options-3"></a>
+<a name="eslint-plugin-jsdoc-rules-no-undefined-types-options-4"></a>
 #### Options
 
 An option object may have the following keys:
@@ -3671,7 +3688,7 @@ Requires that all functions have a description.
 * All functions must have a `@description` tag.
 * Every description tag must have a non-empty description that explains the purpose of the method.
 
-<a name="eslint-plugin-jsdoc-rules-require-description-options-4"></a>
+<a name="eslint-plugin-jsdoc-rules-require-description-options-5"></a>
 #### Options
 
 An options object may have any of the following properties:
@@ -3865,7 +3882,7 @@ Requires that all functions have examples.
 * All functions must have one or more `@example` tags.
 * Every example tag must have a non-empty description that explains the method's usage.
 
-<a name="eslint-plugin-jsdoc-rules-require-example-options-5"></a>
+<a name="eslint-plugin-jsdoc-rules-require-example-options-6"></a>
 #### Options
 
 Has an object option with one optional property:
@@ -3996,7 +4013,7 @@ function quux () {
 
 Requires a hyphen before the `@param` description.
 
-<a name="eslint-plugin-jsdoc-rules-require-hyphen-before-param-description-options-6"></a>
+<a name="eslint-plugin-jsdoc-rules-require-hyphen-before-param-description-options-7"></a>
 #### Options
 
 This rule takes one optional string argument. If it is `"always"` then a problem is raised when there is no hyphen before the description. If it is `"never"` then a problem is raised when there is a hyphen before the description. The default value is `"always"`.
@@ -4102,7 +4119,7 @@ function quux () {
 Checks for presence of jsdoc comments, on class declarations as well as
 functions.
 
-<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-7"></a>
+<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-8"></a>
 #### Options
 
 Accepts one optional options object with the following optional keys.
@@ -5138,7 +5155,7 @@ function quux (foo) {
 
 Requires that all function parameters are documented.
 
-<a name="eslint-plugin-jsdoc-rules-require-param-options-8"></a>
+<a name="eslint-plugin-jsdoc-rules-require-param-options-9"></a>
 #### Options
 
 An options object accepts one optional property:
@@ -6065,7 +6082,7 @@ function quux () {
 
 Requires returns are documented.
 
-<a name="eslint-plugin-jsdoc-rules-require-returns-options-9"></a>
+<a name="eslint-plugin-jsdoc-rules-require-returns-options-10"></a>
 #### Options
 
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document

src/iterateJsdoc.js

@@ -28,7 +28,6 @@ const getUtils = (
   jsdocNode,
   {
     tagNamePreference,
-    additionalTagNames,
     allowEmptyNamepaths,
     overrideReplacesDocs,
     implementsReplacesDocs,
@@ -89,8 +88,8 @@ const getUtils = (
     return isObject && !allowObjectReturn ? ret.replacement : ret;
   };
 
-  utils.isValidTag = (name) => {
-    return jsdocUtils.isValidTag(name, additionalTagNames);
+  utils.isValidTag = (name, definedTags) => {
+    return jsdocUtils.isValidTag(name, definedTags);
   };
 
   utils.hasATag = (name) => {
@@ -261,9 +260,6 @@ const getSettings = (context) => {
   settings.implementsReplacesDocs = _.get(context, 'settings.jsdoc.implementsReplacesDocs');
   settings.augmentsExtendsReplacesDocs = _.get(context, 'settings.jsdoc.augmentsExtendsReplacesDocs');
 
-  // `check-tag-names` only
-  settings.additionalTagNames = _.get(context, 'settings.jsdoc.additionalTagNames') || {};
-
   // `check-examples` only
   settings.exampleCodeRegex = _.get(context, 'settings.jsdoc.exampleCodeRegex') || null;
   settings.rejectExampleCodeRegex = _.get(context, 'settings.jsdoc.rejectExampleCodeRegex') || null;

src/jsdocUtils.js

@@ -79,9 +79,9 @@ const getPreferredTagName = (name : string, tagPreference : Object = {}) : strin
   return name;
 };
 
-const isValidTag = (name : string, additionalTagNames : Object) : boolean => {
+const isValidTag = (name : string, definedTags : Array) : boolean => {
   const validTagNames = _.keys(tagNames).concat(_.flatten(_.values(tagNames)));
-  const additionalTags = additionalTagNames.customTags || [];
+  const additionalTags = definedTags;
   const allTags = validTagNames.concat(additionalTags);
 
   return allTags.includes(name);