fix(require-jsdoc): add fixer to add empty jsdoc block

gajus · Aug 8, 2019 · b48cf1d · b48cf1d
1 parent 37e8300
commit b48cf1d
Show file tree

Hide file tree

Showing 5 changed files with 93 additions and 22 deletions.
diff --git a/README.md b/README.md
@@ -4769,8 +4769,8 @@ function myFunction() {
 /**
  * @func myFunction
  */
- 
- 
+
+
 function myFunction() {
 
 }
@@ -4839,6 +4839,13 @@ function quux (foo) {
 // Options: [{"exemptEmptyFunctions":true}]
 // Message: Missing JSDoc comment.
 
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"minLines":2}}
+// Options: [{"exemptEmptyFunctions":true}]
+// Message: Missing JSDoc comment.
+
 function myFunction() {}
 // Message: Missing JSDoc comment.
 
@@ -5231,10 +5238,10 @@ function myFunction() {
 }
 // Settings: {"jsdoc":{"maxLines":0,"minLines":0}}
 
-/** 
+/**
  * @func myFunction
  */
- 
+
 function myFunction() {
 
 }

diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js
@@ -91,9 +91,7 @@ const getUtils = (
   const utils = {};
 
   utils.stringify = (tagBlock) => {
-    let indent = sourceCode.text.match(/^\n*([ \t]+)/);
-    /* istanbul ignore next */
-    indent = indent ? indent[1] + indent[1].charAt() : ' ';
+    const indent = jsdocUtils.getIndent(sourceCode);
 
     return commentStringify([tagBlock], {indent}).slice(indent.length - 1);
   };

diff --git a/src/jsdocUtils.js b/src/jsdocUtils.js
@@ -601,12 +601,21 @@ const getAncestor = (sourceCode, nde, depth, idx = 0) => {
   return null;
 };
 
+const getIndent = (sourceCode) => {
+  let indent = sourceCode.text.match(/^\n*([ \t]+)/);
+  /* istanbul ignore next */
+  indent = indent ? indent[1] + indent[1].charAt() : ' ';
+
+  return indent;
+};
+
 export default {
   enforcedContexts,
   filterTags,
   getAncestor,
   getContextObject,
   getFunctionParameterNames,
+  getIndent,
   getJsdocParameterNames,
   getJsdocParameterNamesDeep,
   getPreferredTagName,

diff --git a/src/rules/requireJsdoc.js b/src/rules/requireJsdoc.js
@@ -125,6 +125,8 @@ export default {
       url: 'https://github.com/gajus/eslint-plugin-jsdoc'
     },
 
+    fixable: 'code',
+
     messages: {
       missingJsDoc: 'Missing JSDoc comment.'
     },
@@ -158,6 +160,18 @@ export default {
         }
       }
 
+      const fix = (fixer) => {
+        // Default to one line break if the `minLines`/`maxLines` settings allow
+        const lines = settings.minLines === 0 && settings.maxLines >= 1 ? 1 : settings.minLines;
+        const indent = jsdocUtils.getIndent(sourceCode);
+        const insertion = `/**\n${indent}*\n${indent}*/${'\n'.repeat(lines)}${indent.slice(0, -1)}`;
+        const baseNode = [
+          'ExportDefaultDeclaration', 'ExportNamedDeclaration'
+        ].includes(node.parent && node.parent.type) ? node.parent : node;
+
+        return fixer.insertTextBefore(baseNode, insertion);
+      };
+
       if (publicOnly) {
         const opt = {
           ancestorsOnly: Boolean(_.get(publicOnly, 'ancestorsOnly', false)),
@@ -170,12 +184,14 @@ export default {
 
         if (exported && !jsDocNode) {
           context.report({
+            fix,
             messageId: 'missingJsDoc',
             node
           });
         }
       } else {
         context.report({
+          fix,
           messageId: 'missingJsDoc',
           node
         });

diff --git a/test/rules/assertions/requireJsdoc.js b/test/rules/assertions/requireJsdoc.js
@@ -10,7 +10,7 @@ export default {
         * @func myFunction
         */
        function myFunction() {
-       
+
        }
        `,
       errors: [
@@ -30,10 +30,10 @@ export default {
        /**
         * @func myFunction
         */
-        
-        
+
+
        function myFunction() {
-       
+
        }
        `,
       errors: [
@@ -50,7 +50,7 @@ export default {
     {
       code: `
        /** @func myFunction */ function myFunction() {
-       
+
        }
        `,
       errors: [
@@ -245,6 +245,12 @@ export default {
           ClassDeclaration: true
         }
       }],
+      output: `
+        /**
+         *
+         */
+        export default class {}
+      `,
       parserOptions: {
         sourceType: 'module'
       }
@@ -288,7 +294,42 @@ export default {
       ],
       options: [
         {exemptEmptyFunctions: true}
-      ]
+      ],
+      output: `
+        /**
+         *
+         */
+        function quux (foo) {
+
+        }`
+    },
+    {
+      code: `
+        function quux (foo) {
+
+        }`,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc comment.'
+        }
+      ],
+      options: [
+        {exemptEmptyFunctions: true}
+      ],
+      output: `
+        /**
+         *
+         */
+
+        function quux (foo) {
+
+        }`,
+      settings: {
+        jsdoc: {
+          minLines: 2
+        }
+      }
     },
     {
       code: 'function myFunction() {}',
@@ -1195,9 +1236,9 @@ export default {
        /**
         * @func myFunction
         */
-       
+
        function myFunction() {
-       
+
        }
        `,
     settings: {
@@ -1212,10 +1253,10 @@ export default {
      /**
       * @func myFunction
       */
-     
-     
+
+
      function myFunction() {
-     
+
      }
      `,
     settings: {
@@ -1228,7 +1269,7 @@ export default {
   {
     code: `
         /** @func myFunction */  function myFunction() {
-   
+
         }
    `,
     settings: {
@@ -1240,12 +1281,12 @@ export default {
   },
   {
     code: `
-        /** 
+        /**
          * @func myFunction
          */
-         
+
         function myFunction() {
- 
+
         }
     `,
     settings: {