feat(match-description): allow description and desc tags to be matched for validation

Author: brettz9

.README/rules/match-description.md

@@ -82,6 +82,6 @@ Overrides the default contexts (see below).
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A by default but see `tags` options|
 |Settings||
-|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `mainDescription`, `matchDescription`|
+|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return', 'description', 'desc'), `mainDescription`, `matchDescription`|
 
 <!-- assertions matchDescription -->

README.md

@@ -2495,7 +2495,7 @@ Overrides the default contexts (see below).
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A by default but see `tags` options|
 |Settings||
-|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `mainDescription`, `matchDescription`|
+|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return', 'description', 'desc'), `mainDescription`, `matchDescription`|
 
 The following patterns are considered problems:
 
@@ -2571,6 +2571,17 @@ function quux (foo) {
 // Options: [{"tags":{"param":true}}]
 // Message: JSDoc description does not satisfy the regex pattern.
 
+/**
+ * Foo.
+ *
+ * @description foo foo.
+ */
+function quux (foo) {
+
+}
+// Options: [{"tags":{"description":true}}]
+// Message: JSDoc description does not satisfy the regex pattern.
+
 /**
  * Foo
  *
@@ -2695,6 +2706,16 @@ function quux () {
 // Options: [{"tags":{"param":"[А-Я][А-я]+\\."}}]
 // Message: JSDoc description does not satisfy the regex pattern.
 
+/**
+ * @description notRet
+ * @returns Тест.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"description":"[А-Я][А-я]+\\."}}]
+// Message: JSDoc description does not satisfy the regex pattern.
+
 /**
  * foo.
  */
@@ -2784,6 +2805,15 @@ function quux () {
 }
 // Options: [{"tags":{"returns":"[А-Я][А-я]+\\."}}]
 
+/**
+ * @param notRet
+ * @description Тест.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"description":"[А-Я][А-я]+\\."}}]
+
 /**
  * Foo
  * bar.
@@ -2800,6 +2830,14 @@ function quux () {
 }
 // Options: [{"tags":{"returns":true}}]
 
+/**
+ * @description Foo bar.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"description":true}}]
+
 /**
  * Foo. {@see Math.sin}.
  */
@@ -2921,6 +2959,14 @@ const q = {
 
 };
 // Options: [{"contexts":[]}]
+
+/**
+ * @description foo.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"param":true}}]
 ````
 
 

src/rules/matchDescription.js

@@ -53,9 +53,19 @@ export default iterateJsdoc(({
     return;
   }
 
+  const hasOptionTag = (tagName) => {
+    return Boolean(options.tags[tagName]);
+  };
+
+  utils.forEachPreferredTag('description', (matchingJsdocTag, targetTagName) => {
+    const description = (matchingJsdocTag.name + ' ' + matchingJsdocTag.description).trim();
+    if (hasOptionTag(targetTagName)) {
+      validateDescription(description, matchingJsdocTag);
+    }
+  });
+
   const tags = utils.filterTags(({tag}) => {
-    return tagsWithDescriptions.includes(tag) &&
-      {}.hasOwnProperty.call(options.tags, tag) && options.tags[tag];
+    return tagsWithDescriptions.includes(tag) && hasOptionTag(tag);
   });
 
   tags.some((tag) => {

test/rules/assertions/matchDescription.js

@@ -160,6 +160,31 @@ export default {
         }
       ]
     },
+    {
+      code: `
+          /**
+           * Foo.
+           *
+           * @description foo foo.
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          line: 5,
+          message: 'JSDoc description does not satisfy the regex pattern.'
+        }
+      ],
+      options: [
+        {
+          tags: {
+            description: true
+          }
+        }
+      ]
+    },
     {
       code: `
           /**
@@ -440,6 +465,28 @@ export default {
         }
       }]
     },
+    {
+      code: `
+          /**
+           * @description notRet
+           * @returns Тест.
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'JSDoc description does not satisfy the regex pattern.'
+        }
+      ],
+      options: [{
+        tags: {
+          description: '[\u0410-\u042F][\u0410-\u044F]+\\.'
+        }
+      }]
+    },
     {
       code: `
           /**
@@ -615,6 +662,22 @@ export default {
         }
       }]
     },
+    {
+      code: `
+          /**
+           * @param notRet
+           * @description Тест.
+           */
+          function quux () {
+
+          }
+      `,
+      options: [{
+        tags: {
+          description: '[\u0410-\u042F][\u0410-\u044F]+\\.'
+        }
+      }]
+    },
     {
       code: `
           /**
@@ -643,6 +706,23 @@ export default {
         }
       ]
     },
+    {
+      code: `
+          /**
+           * @description Foo bar.
+           */
+          function quux () {
+
+          }
+      `,
+      options: [
+        {
+          tags: {
+            description: true
+          }
+        }
+      ]
+    },
     {
       code: `
           /**
@@ -842,6 +922,21 @@ export default {
           ]
         }
       ]
+    },
+    {
+      code: `
+          /**
+           * @description foo.
+           */
+          function quux () {
+
+          }
+      `,
+      options: [
+        {tags: {
+          param: true
+        }}
+      ]
     }
   ]
 };