From dfd2a8a0b5fbff4e5840c8d65b82c61ab54d7f87 Mon Sep 17 00:00:00 2001
From: Brett Zamir <brettz9@yahoo.com>
Date: Mon, 11 Sep 2023 14:53:55 -0700
Subject: [PATCH] feat(`require-returns`): add optional fixer

---
 .README/rules/require-returns.md        |  4 +++-
 docs/rules/require-returns.md           | 14 ++++++++++-
 src/rules/requireReturns.js             |  9 ++++++-
 test/rules/assertions/requireReturns.js | 32 +++++++++++++++++++++++++
 4 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/.README/rules/require-returns.md b/.README/rules/require-returns.md
index 240c7dd27..dc055e9d6 100644
--- a/.README/rules/require-returns.md
+++ b/.README/rules/require-returns.md
@@ -42,6 +42,8 @@ Will also report if multiple `@returns` tags are present.
     `forceReturnsWithAsync` option is set with a present `@async` tag
     (since we are not checking against the actual `return` values in these
     cases).
+- `enableFixer` - Whether to enable the fixer to add a blank `@returns`.
+    Defaults to `false`.
 
 ## Context and settings
 
@@ -51,7 +53,7 @@ Will also report if multiple `@returns` tags are present.
 | Tags     | `returns` |
 | Aliases  | `return` |
 |Recommended|true|
-| Options  |`checkConstructors`, `checkGetters`, `contexts`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync`|
+| Options  |`checkConstructors`, `checkGetters`, `contexts`, `enableFixer`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync`|
 | Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 ## Failing examples
diff --git a/docs/rules/require-returns.md b/docs/rules/require-returns.md
index 1f54d2073..847c6b889 100644
--- a/docs/rules/require-returns.md
+++ b/docs/rules/require-returns.md
@@ -50,6 +50,8 @@ Will also report if multiple `@returns` tags are present.
     `forceReturnsWithAsync` option is set with a present `@async` tag
     (since we are not checking against the actual `return` values in these
     cases).
+- `enableFixer` - Whether to enable the fixer to add a blank `@returns`.
+    Defaults to `false`.
 
 <a name="user-content-require-returns-context-and-settings"></a>
 <a name="require-returns-context-and-settings"></a>
@@ -61,7 +63,7 @@ Will also report if multiple `@returns` tags are present.
 | Tags     | `returns` |
 | Aliases  | `return` |
 |Recommended|true|
-| Options  |`checkConstructors`, `checkGetters`, `contexts`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync`|
+| Options  |`checkConstructors`, `checkGetters`, `contexts`, `enableFixer`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync`|
 | Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 <a name="user-content-require-returns-failing-examples"></a>
@@ -80,6 +82,16 @@ function quux (foo) {
 }
 // Message: Missing JSDoc @returns declaration.
 
+/**
+ *
+ */
+function quux (foo) {
+
+  return foo;
+}
+// "jsdoc/require-returns": ["error"|"warn", {"enableFixer":true}]
+// Message: Missing JSDoc @returns declaration.
+
 /**
  *
  */
diff --git a/src/rules/requireReturns.js b/src/rules/requireReturns.js
index 582aa39ea..8489c171d 100644
--- a/src/rules/requireReturns.js
+++ b/src/rules/requireReturns.js
@@ -44,6 +44,7 @@ export default iterateJsdoc(({
 }) => {
   const {
     contexts,
+    enableFixer = false,
     forceRequireReturn = false,
     forceReturnsWithAsync = false,
   } = context.options[0] || {};
@@ -110,7 +111,9 @@ export default iterateJsdoc(({
   };
 
   if (shouldReport()) {
-    report(`Missing JSDoc @${tagName} declaration.`);
+    utils.reportJSDoc(`Missing JSDoc @${tagName} declaration.`, null, enableFixer ? () => {
+      utils.addTag(tagName);
+    } : null);
   }
 }, {
   contextDefaults: true,
@@ -119,6 +122,7 @@ export default iterateJsdoc(({
       description: 'Requires that returns are documented.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns.md#repos-sticky-header',
     },
+    fixable: 'code',
     schema: [
       {
         additionalProperties: false,
@@ -156,6 +160,9 @@ export default iterateJsdoc(({
             },
             type: 'array',
           },
+          enableFixer: {
+            type: 'boolean',
+          },
           exemptedBy: {
             items: {
               type: 'string',
diff --git a/test/rules/assertions/requireReturns.js b/test/rules/assertions/requireReturns.js
index 81ba52db9..315c5ab4d 100644
--- a/test/rules/assertions/requireReturns.js
+++ b/test/rules/assertions/requireReturns.js
@@ -17,6 +17,38 @@ export default {
         },
       ],
     },
+    {
+      code: `
+        /**
+         *
+         */
+        function quux (foo) {
+
+          return foo;
+        }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @returns declaration.',
+        },
+      ],
+      options: [
+        {
+          enableFixer: true,
+        },
+      ],
+      output: `
+        /**
+         *
+         * @returns
+         */
+        function quux (foo) {
+
+          return foo;
+        }
+      `,
+    },
     {
       code: `
           /**