fix(require-jsdoc): allow additional contexts to block preceeding e…

…xport and find jsdoc

Adds fixes for TSTypeAliasDeclaration and TSEnumDeclaration similar to the recent changes to support TSInterfaceDeclaration.

Adding these additional types to the switch statement pushed function complexity over 20, so getJSDocComment was split into two functions.

README.md

@@ -5890,6 +5890,50 @@ interface Example {
   test: string
 }
 // Options: [{"contexts":["TSInterfaceDeclaration"]}]
+
+/**
+ * This example type is great!
+ */
+export type Example = {
+  /**
+   * My super test string!
+   */
+  test: string
+};
+// Options: [{"contexts":["TSTypeAliasDeclaration"]}]
+
+/**
+ * This example type is great!
+ */
+type Example = {
+  /**
+   * My super test string!
+   */
+  test: string
+};
+// Options: [{"contexts":["TSTypeAliasDeclaration"]}]
+
+/**
+ * This example enum is great!
+ */
+export enum Example {
+  /**
+   * My super test enum!
+   */
+  test = 123
+}
+// Options: [{"contexts":["TSEnumDeclaration"]}]
+
+/**
+ * This example enum is great!
+ */
+enum Example {
+  /**
+   * My super test enum!
+   */
+  test = 123
+}
+// Options: [{"contexts":["TSEnumDeclaration"]}]
 ````
 
 

src/eslint/getJSDocComment.js

@@ -27,48 +27,23 @@ const looksLikeExport = function (astNode) {
 };
 
 /**
- * Retrieves the JSDoc comment for a given node.
+ * Reduces the provided node to the appropriate node for evaluating JSDoc comment status.
  *
- * @param {SourceCode} sourceCode The ESLint SourceCode
- * @param {ASTNode} node The AST node to get the comment for.
- * @param {object} settings The settings in context
- * @returns {Token|null} The Block comment token containing the JSDoc comment
- *    for the given node or null if not found.
- * @public
- * @deprecated
+ * @param {ASTNode} node An AST node.
+ * @param {SourceCode} sourceCode The ESLint SourceCode.
+ * @returns {ASTNode} The AST node that can be evaluated for appropriate JSDoc comments.
+ * @private
  */
-const getJSDocComment = function (sourceCode, node, settings) {
-  /**
-   * Checks for the presence of a JSDoc comment for the given node and returns it.
-   *
-   * @param {ASTNode} astNode The AST node to get the comment for.
-   * @returns {Token|null} The Block comment token containing the JSDoc comment
-   *    for the given node or null if not found.
-   * @private
-   */
-  const findJSDocComment = (astNode) => {
-    const tokenBefore = sourceCode.getTokenBefore(astNode, {includeComments: true});
-    const {minLines, maxLines} = settings;
-    if (
-      tokenBefore &&
-      isCommentToken(tokenBefore) &&
-      tokenBefore.type === 'Block' &&
-      tokenBefore.value.charAt(0) === '*' &&
-      astNode.loc.start.line - tokenBefore.loc.end.line >= minLines &&
-      astNode.loc.start.line - tokenBefore.loc.end.line <= maxLines
-    ) {
-      return tokenBefore;
-    }
-
-    return null;
-  };
+const getReducedASTNode = function (node, sourceCode) {
   let {parent} = node;
 
   switch (node.type) {
   case 'TSInterfaceDeclaration':
+  case 'TSTypeAliasDeclaration':
+  case 'TSEnumDeclaration':
   case 'ClassDeclaration':
   case 'FunctionDeclaration':
-    return findJSDocComment(looksLikeExport(parent) ? parent : node);
+    return looksLikeExport(parent) ? parent : node;
 
   case 'ClassExpression':
   case 'ObjectExpression':
@@ -91,19 +66,60 @@ const getJSDocComment = function (sourceCode, node, settings) {
       }
 
       if (parent && parent.type !== 'FunctionDeclaration' && parent.type !== 'Program') {
-        return findJSDocComment(parent);
+        return parent;
       }
     }
 
-    return findJSDocComment(node);
+    return node;
 
   default:
-    if (!node) {
-      return null;
+    return node;
+  }
+};
+
+/**
+ * Retrieves the JSDoc comment for a given node.
+ *
+ * @param {SourceCode} sourceCode The ESLint SourceCode
+ * @param {ASTNode} node The AST node to get the comment for.
+ * @param {object} settings The settings in context
+ * @returns {Token|null} The Block comment token containing the JSDoc comment
+ *    for the given node or null if not found.
+ * @public
+ * @deprecated
+ */
+const getJSDocComment = function (sourceCode, node, settings) {
+  /**
+   * Checks for the presence of a JSDoc comment for the given node and returns it.
+   *
+   * @param {ASTNode} astNode The AST node to get the comment for.
+   * @returns {Token|null} The Block comment token containing the JSDoc comment
+   *    for the given node or null if not found.
+   * @private
+   */
+  const findJSDocComment = (astNode) => {
+    const tokenBefore = sourceCode.getTokenBefore(astNode, {includeComments: true});
+    const {minLines, maxLines} = settings;
+    if (
+      tokenBefore &&
+      isCommentToken(tokenBefore) &&
+      tokenBefore.type === 'Block' &&
+      tokenBefore.value.charAt(0) === '*' &&
+      astNode.loc.start.line - tokenBefore.loc.end.line >= minLines &&
+      astNode.loc.start.line - tokenBefore.loc.end.line <= maxLines
+    ) {
+      return tokenBefore;
     }
 
-    return findJSDocComment(node);
+    return null;
+  };
+
+  const reducedNode = getReducedASTNode(node, sourceCode);
+  if (!reducedNode) {
+    return null;
   }
+
+  return findJSDocComment(reducedNode);
 };
 
 export default getJSDocComment;

test/rules/assertions/requireJsdoc.js

@@ -2230,6 +2230,100 @@ export default {
     parserOptions: {
       sourceType: 'module',
     },
+  }, {
+    code: `
+    /**
+     * This example type is great!
+     */
+    export type Example = {
+      /**
+       * My super test string!
+       */
+      test: string
+    };
+    `,
+    options: [
+      {
+        contexts: [
+          'TSTypeAliasDeclaration',
+        ],
+      },
+    ],
+    parser: require.resolve('@typescript-eslint/parser'),
+    parserOptions: {
+      sourceType: 'module',
+    },
+  },
+  {
+    code: `
+    /**
+     * This example type is great!
+     */
+    type Example = {
+      /**
+       * My super test string!
+       */
+      test: string
+    };
+    `,
+    options: [
+      {
+        contexts: [
+          'TSTypeAliasDeclaration',
+        ],
+      },
+    ],
+    parser: require.resolve('@typescript-eslint/parser'),
+    parserOptions: {
+      sourceType: 'module',
+    },
+  }, {
+    code: `
+    /**
+     * This example enum is great!
+     */
+    export enum Example {
+      /**
+       * My super test enum!
+       */
+      test = 123
+    }
+    `,
+    options: [
+      {
+        contexts: [
+          'TSEnumDeclaration',
+        ],
+      },
+    ],
+    parser: require.resolve('@typescript-eslint/parser'),
+    parserOptions: {
+      sourceType: 'module',
+    },
+  },
+  {
+    code: `
+    /**
+     * This example enum is great!
+     */
+    enum Example {
+      /**
+       * My super test enum!
+       */
+      test = 123
+    }
+    `,
+    options: [
+      {
+        contexts: [
+          'TSEnumDeclaration',
+        ],
+      },
+    ],
+    parser: require.resolve('@typescript-eslint/parser'),
+    parserOptions: {
+      sourceType: 'module',
+    },
   },
   ],
 };