feat(require-description): report more precisely the action to take…

… when "body" `descriptionStyle` is set and where user has a desc/description tag; fixes #608 (#609)
gajus · Jul 13, 2020 · 69fd79d · 69fd79d
1 parent 6f94d12
commit 69fd79d
Show file tree

Hide file tree

Showing 3 changed files with 65 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -7275,6 +7275,24 @@ function quux () {
 // Options: [{"descriptionStyle":"body"}]
 // Message: Missing JSDoc block description.
 
+/**
+ * @desc Not a blank description
+ */
+function quux () {
+
+}
+// Options: [{"descriptionStyle":"body"}]
+// Message: Remove the @desc tag to leave a plain block description or add additional description text above the @desc line.
+
+/**
+ * @description Not a blank description
+ */
+function quux () {
+
+}
+// Options: [{"descriptionStyle":"body"}]
+// Message: Remove the @description tag to leave a plain block description or add additional description text above the @description line.
+
 /**
  *
  */

diff --git a/src/rules/requireDescription.js b/src/rules/requireDescription.js
@@ -40,7 +40,13 @@ export default iterateJsdoc(({
     }
 
     if (descriptionStyle === 'body') {
-      report('Missing JSDoc block description.');
+      const descTags = utils.getPresentTags(['desc', 'description']);
+      if (descTags.length) {
+        const [{tag: tagName}] = descTags;
+        report(`Remove the @${tagName} tag to leave a plain block description or add additional description text above the @${tagName} line.`);
+      } else {
+        report('Missing JSDoc block description.');
+      }
 
       return;
     }

diff --git a/test/rules/assertions/requireDescription.js b/test/rules/assertions/requireDescription.js
@@ -60,6 +60,46 @@ export default {
         },
       ],
     },
+    {
+      code: `
+          /**
+           * @desc Not a blank description
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Remove the @desc tag to leave a plain block description or add additional description text above the @desc line.',
+        },
+      ],
+      options: [
+        {
+          descriptionStyle: 'body',
+        },
+      ],
+    },
+    {
+      code: `
+          /**
+           * @description Not a blank description
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Remove the @description tag to leave a plain block description or add additional description text above the @description line.',
+        },
+      ],
+      options: [
+        {
+          descriptionStyle: 'body',
+        },
+      ],
+    },
     {
       code: `
           /**