fix(require-jsdoc): placement of jsdoc block by fixer; fixes #369, #403…

…, #502, #522 Properly finds base node for affixing jsdoc block and uses to determine appropriate indent (finds base node in a manner sensitive to context, reusing existing and more accurate detection for this purpose, improving detection for function expressions, including arrow function expressions and method definitions). As part of `getReducedASTNode` (used also within `getJSDocComment`), need to stop at `VariableDeclaration` or `ExpressionStatement` (where comments shouldl be checked). Needed for proper function expression documentation placement. Also provides `getJSDocComment` as a named export
gajus · May 3, 2020 · c1b5b46 · c1b5b46
1 parent 1f010f9
commit c1b5b46
Show file tree

Hide file tree

Showing 4 changed files with 178 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -7994,6 +7994,38 @@ export default class Test {
 }
 // Options: [{"contexts":["MethodDefinition:not([accessibility=\"private\"]) > FunctionExpression"],"publicOnly":true,"require":{"ArrowFunctionExpression":false,"ClassDeclaration":false,"ClassExpression":false,"FunctionDeclaration":false,"FunctionExpression":false,"MethodDefinition":false}}]
 // Message: Missing JSDoc comment.
+
+e = function () {
+};
+// Options: [{"require":{"FunctionDeclaration":false,"FunctionExpression":true}}]
+// Message: Missing JSDoc comment.
+
+/**
+ *
+ */
+export class Class {
+    test = 1;
+
+    foo() {
+        this.test = 2;
+    }
+}
+// Options: [{"require":{"FunctionDeclaration":false,"MethodDefinition":true}}]
+// Message: Missing JSDoc comment.
+
+class Dog {
+  eat() {
+
+  }
+}
+// Options: [{"require":{"FunctionDeclaration":false,"MethodDefinition":true}}]
+// Message: Missing JSDoc comment.
+
+const hello = name => {
+  document.body.textContent = "Hello, " + name + "!";
+};
+// Options: [{"require":{"ArrowFunctionExpression":true,"FunctionDeclaration":false}}]
+// Message: Missing JSDoc comment.
 ````
 
 The following patterns are not considered problems:

diff --git a/src/eslint/getJSDocComment.js b/src/eslint/getJSDocComment.js
@@ -142,6 +142,8 @@ const getReducedASTNode = function (node, sourceCode) {
       while (
         !sourceCode.getCommentsBefore(parent).length &&
         !/Function/u.test(parent.type) &&
+        parent.type !== 'VariableDeclaration' &&
+        parent.type !== 'ExpressionStatement' &&
         parent.type !== 'MethodDefinition' &&
         parent.type !== 'Property'
       ) {
@@ -227,5 +229,5 @@ const getJSDocComment = function (sourceCode, node, settings) {
   return findJSDocComment(reducedNode);
 };
 
-export {getReducedASTNode};
+export {getReducedASTNode, getJSDocComment};
 export default getJSDocComment;
diff --git a/src/rules/requireJsdoc.js b/src/rules/requireJsdoc.js
@@ -1,7 +1,7 @@
 import _ from 'lodash';
 import jsdocUtils from '../jsdocUtils';
 import exportParser from '../exportParser';
-import getJSDocComment from '../eslint/getJSDocComment';
+import {getJSDocComment, getReducedASTNode} from '../eslint/getJSDocComment';
 import warnRemovedSettings from '../warnRemovedSettings';
 import {getSettings} from '../iterateJsdoc';
 
@@ -141,11 +141,17 @@ 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 baseNode = getReducedASTNode(node, sourceCode);
+
+        const indent = jsdocUtils.getIndent({
+          text: sourceCode.getText(
+            baseNode,
+
+            // Could also use `baseNode.start - 1`
+            baseNode.loc.start.column,
+          ),
+        });
         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);
       };

diff --git a/test/rules/assertions/requireJsdoc.js b/test/rules/assertions/requireJsdoc.js
@@ -1252,6 +1252,138 @@ export default {
         sourceType: 'module',
       },
     },
+    {
+      code: `
+      e = function () {
+      };
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc comment.',
+        },
+      ],
+      options: [
+        {
+          require: {
+            FunctionDeclaration: false,
+            FunctionExpression: true,
+          },
+        },
+      ],
+      output: `
+      /**
+       *
+       */
+      e = function () {
+      };
+      `,
+    },
+    {
+      code: `
+      /**
+       *
+       */
+      export class Class {
+          test = 1;
+
+          foo() {
+              this.test = 2;
+          }
+      }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc comment.',
+        },
+      ],
+      options: [
+        {
+          require: {
+            FunctionDeclaration: false,
+            MethodDefinition: true,
+          },
+        },
+      ],
+      output: `
+      /**
+       *
+       */
+      export class Class {
+          test = 1;
+
+          /**
+           *
+           */
+          foo() {
+              this.test = 2;
+          }
+      }
+      `,
+      parser: require.resolve('@typescript-eslint/parser'),
+      parserOptions: {
+        sourceType: 'module',
+      },
+    },
+    {
+      code: `
+      class Dog {
+        eat() {
+
+        }
+      }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc comment.',
+        },
+      ],
+      options: [
+        {
+          require: {
+            FunctionDeclaration: false,
+            MethodDefinition: true,
+          },
+        },
+      ],
+      output: `
+      class Dog {
+        /**
+         *
+         */
+        eat() {
+
+        }
+      }
+      `,
+    },
+    {
+      code: `
+      const hello = name => {
+        document.body.textContent = "Hello, " + name + "!";
+      };
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc comment.',
+        },
+      ],
+      options: [
+        {
+          require: {
+            ArrowFunctionExpression: true,
+            FunctionDeclaration: false,
+          },
+        },
+      ],
+      output: `
+      /**
+       *
+       */
+      const hello = name => {
+        document.body.textContent = "Hello, " + name + "!";
+      };
+      `,
+    },
   ],
   valid: [{
     code: `