From 69fd79d85c70278d7a199efe7e3d2578fd331346 Mon Sep 17 00:00:00 2001
From: Brett Zamir <brettz9@yahoo.com>
Date: Mon, 13 Jul 2020 19:28:45 +0800
Subject: [PATCH] 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)

---
 README.md                                   | 18 ++++++++++
 src/rules/requireDescription.js             |  8 ++++-
 test/rules/assertions/requireDescription.js | 40 +++++++++++++++++++++
 3 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e0aa71e47..cf3064ede 100644
--- 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
index 90c328dd7..b132cc4ba 100644
--- 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
index d2ee2cb98..37bb24676 100644
--- 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: `
           /**