feat(require-hyphen-before-param-description): add tags option for setting specific tags (or any tags) to follow rules for or against hyphen descriptions; now allows property to be set differently than param; fixes gajus#553

BREAKING CHANGE:

`{checkProperties: true}` should be replaced by: `{tags: {'property': 'always|never'}}`

Author: brettz9

.README/rules/require-hyphen-before-param-description.md

@@ -10,16 +10,22 @@ If the string 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"`.
 
-The options object may have the following properties:
+The options object may have the following properties to indicate behavior for
+other tags besides the `@param` tag (or the `@arg` tag if so set):
 
-- `checkProperties` - Boolean on whether to also apply the rule to `@property`
-  tags.
+- `tags` - Object whose keys indicate different tags to check for the
+  presence or absence of hyphens; the key value should be "always" or "never",
+  indicating how hyphens are to be applied, e.g., `{property: 'never'}`
+  to ensure `@property` never uses hyphens. A key can also be set as `*`, e.g.,
+  `'*': 'always'` to apply hyphen checking to any tag (besides the preferred
+  `@param` tag which follows the main string option setting and besides any
+  other `tags` entries).
 
 |||
 |---|---|
 |Context|everywhere|
-|Tags|`param` and optionally `property`|
-|Aliases|`arg`, `argument`; optionally `prop`|
-|Options|(a string matching `"always"|"never"`) followed by an optional object with a `checkProperties` property|
+|Tags|`param` and optionally other tags within `tags`|
+|Aliases|`arg`, `argument`; potentially `prop` or other aliases|
+|Options|(a string matching `"always"|"never"`) followed by an optional object with a `tags` property|
 
 <!-- assertions requireHyphenBeforeParamDescription -->

README.md

@@ -7930,17 +7930,23 @@ If the string 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"`.
 
-The options object may have the following properties:
+The options object may have the following properties to indicate behavior for
+other tags besides the `@param` tag (or the `@arg` tag if so set):
 
-- `checkProperties` - Boolean on whether to also apply the rule to `@property`
-  tags.
+- `tags` - Object whose keys indicate different tags to check for the
+  presence or absence of hyphens; the key value should be "always" or "never",
+  indicating how hyphens are to be applied, e.g., `{property: 'never'}`
+  to ensure `@property` never uses hyphens. A key can also be set as `*`, e.g.,
+  `'*': 'always'` to apply hyphen checking to any tag (besides the preferred
+  `@param` tag which follows the main string option setting and besides any
+  other `tags` entries).
 
 |||
 |---|---|
 |Context|everywhere|
-|Tags|`param` and optionally `property`|
-|Aliases|`arg`, `argument`; optionally `prop`|
-|Options|(a string matching `"always"|"never"`) followed by an optional object with a `checkProperties` property|
+|Tags|`param` and optionally other tags within `tags`|
+|Aliases|`arg`, `argument`; potentially `prop` or other aliases|
+|Options|(a string matching `"always"|"never"`) followed by an optional object with a `tags` property|
 
 The following patterns are considered problems:
 
@@ -7959,6 +7965,25 @@ function quux () {
  */
 function quux () {
 
+}
+// Options: ["always",{"tags":{"*":"never"}}]
+// Message: There must be a hyphen before @param description.
+
+/**
+ * @param foo Foo.
+ * @returns {SomeType} - Hyphen here.
+ */
+function quux () {
+
+}
+// Options: ["always",{"tags":{"*":"never","returns":"always"}}]
+// Message: There must be a hyphen before @param description.
+
+/**
+ * @param foo Foo.
+ */
+function quux () {
+
 }
 // Message: There must be a hyphen before @param description.
 
@@ -8005,15 +8030,25 @@ function quux (foo) {
  * @typedef {SomeType} ATypeDefName
  * @property foo Foo.
  */
-// Options: ["always",{"checkProperties":true}]
+// Options: ["always",{"tags":{"property":"always"}}]
 // Message: There must be a hyphen before @property description.
 
 /**
  * @typedef {SomeType} ATypeDefName
  * @property foo - Foo.
  */
-// Options: ["never",{"checkProperties":true}]
+// Options: ["never",{"tags":{"property":"never"}}]
 // Message: There must be no hyphen before @property description.
+
+/**
+ * @param foo Foo.
+ * @returns {SomeType} - A description.
+ */
+function quux () {
+
+}
+// Options: ["always",{"tags":{"returns":"never"}}]
+// Message: There must be a hyphen before @param description.
 ````
 
 The following patterns are not considered problems:
@@ -8027,6 +8062,15 @@ function quux () {
 }
 // Options: ["always"]
 
+/**
+ * @param foo - Foo.
+ * @returns {SomeType} A description.
+ */
+function quux () {
+
+}
+// Options: ["always",{"tags":{"returns":"never"}}]
+
 /**
  * @param foo Foo.
  */
@@ -8042,17 +8086,31 @@ function quux () {
 
 }
 
+/**
+ *
+ */
+function quux () {
+
+}
+// Options: ["always",{"tags":{"*":"always"}}]
+
 /**
  * @typedef {SomeType} ATypeDefName
  * @property foo - Foo.
  */
-// Options: ["always",{"checkProperties":true}]
+// Options: ["always",{"tags":{"property":"always"}}]
 
 /**
  * @typedef {SomeType} ATypeDefName
  * @property foo Foo.
  */
-// Options: ["never",{"checkProperties":true}]
+// Options: ["never",{"tags":{"property":"never"}}]
+
+/**
+ * @typedef {SomeType} ATypeDefName
+ * @property foo - Foo.
+ */
+// Options: ["never",{"tags":{"*":"always"}}]
 ````
 
 

src/rules/requireHyphenBeforeParamDescription.js

@@ -5,12 +5,13 @@ export default iterateJsdoc(({
   utils,
   report,
   context,
+  jsdoc,
   jsdocNode,
 }) => {
-  const [circumstance, {checkProperties} = {}] = context.options;
-  const always = !circumstance || circumstance === 'always';
+  const [mainCircumstance, {tags} = {}] = context.options;
 
-  const checkHyphens = (jsdocTag, targetTagName) => {
+  const checkHyphens = (jsdocTag, targetTagName, circumstance = mainCircumstance) => {
+    const always = !circumstance || circumstance === 'always';
     if (!jsdocTag.description) {
       return;
     }
@@ -47,8 +48,28 @@ export default iterateJsdoc(({
   };
 
   utils.forEachPreferredTag('param', checkHyphens);
-  if (checkProperties) {
-    utils.forEachPreferredTag('property', checkHyphens);
+  if (tags) {
+    const tagEntries = Object.entries(tags);
+    tagEntries.forEach(([tagName, circumstance]) => {
+      if (tagName === '*') {
+        const preferredParamTag = utils.getPreferredTagName({tagName: 'param'});
+        (jsdoc.tags || []).forEach(({tag}) => {
+          if (tag === preferredParamTag || tagEntries.some(([tagNme]) => {
+            return tagNme !== '*' && tagNme === tag;
+          })) {
+            return;
+          }
+          utils.forEachPreferredTag(tag, (jsdocTag, targetTagName) => {
+            checkHyphens(jsdocTag, targetTagName, circumstance);
+          });
+        });
+
+        return;
+      }
+      utils.forEachPreferredTag(tagName, (jsdocTag, targetTagName) => {
+        checkHyphens(jsdocTag, targetTagName, circumstance);
+      });
+    });
   }
 }, {
   iterateAllJsdocs: true,
@@ -62,9 +83,22 @@ export default iterateJsdoc(({
       {
         additionalProperties: false,
         properties: {
-          checkProperties: {
-            default: false,
-            type: 'boolean',
+          tags: {
+            anyOf: [
+              {
+                patternProperties: {
+                  '.*': {
+                    enum: ['always', 'never'],
+                    type: 'string',
+                  },
+                },
+                type: 'object',
+              },
+              {
+                enum: ['any'],
+                type: 'string',
+              },
+            ],
           },
         },
         type: 'object',