feat(require-returns): add optional fixer

Author: brettz9

.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

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.
+
 /**
  *
  */

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',

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: `
           /**