fix(require-jsdoc): check interfaces within file for comment blocks; fixes #768 (#1410)

Author: brettz9

docs/rules/require-jsdoc.md

@@ -1028,6 +1028,19 @@ type Props = {
 export type { Props as ComponentProps };
 // "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["VariableDeclaration","TSTypeAliasDeclaration","TSPropertySignature","TSInterfaceDeclaration","TSMethodSignature","TSEnumDeclaration"],"enableFixer":true,"publicOnly":{"esm":true},"require":{"ArrowFunctionExpression":true,"ClassDeclaration":true,"ClassExpression":true,"FunctionDeclaration":true,"FunctionExpression":true,"MethodDefinition":true}}]
 // Message: Missing JSDoc comment.
+
+export interface A {
+  a: string;
+}
+
+export class B implements A, B {
+  a = 'abc';
+  public f(): void {
+    //
+  }
+}
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["MethodDefinition"]}]
+// Message: Missing JSDoc comment.
 ````
 
 
@@ -1931,5 +1944,21 @@ export function arrayMap<Target, Source extends Array<unknown>>(data: Source, ca
 export function arrayMap<Target, Source extends AnyArrayType>(data: Source, callback: MapCallback<Target, Source>): AnyArrayType<Target> {
   return data.map(callback);
 }
+
+export interface A {
+  a: string;
+  /**
+   * Documentation.
+   */
+  f(): void;
+}
+
+export class B implements A {
+  a = 'abc';
+  public f(): void {
+    //
+  }
+}
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["MethodDefinition"]}]
 ````
 

src/rules/requireJsdoc.js

@@ -173,6 +173,100 @@ const OPTIONS_SCHEMA = {
   type: 'object',
 };
 
+/**
+ * @param {string} interfaceName
+ * @param {string} methodName
+ * @param {import("eslint").Scope.Scope | null} scope
+ * @returns {import('@typescript-eslint/types').TSESTree.TSMethodSignature|null}
+ */
+const getMethodOnInterface = (interfaceName, methodName, scope) => {
+  let scp = scope;
+  while (scp) {
+    for (const {
+      identifiers,
+      name,
+    } of scp.variables) {
+      if (interfaceName !== name) {
+        continue;
+      }
+
+      for (const identifier of identifiers) {
+        const interfaceDeclaration = /** @type {import('@typescript-eslint/types').TSESTree.Identifier & {parent: import('@typescript-eslint/types').TSESTree.TSInterfaceDeclaration}} */ (
+          identifier
+        ).parent;
+        /* c8 ignore next 3 -- TS */
+        if (interfaceDeclaration.type !== 'TSInterfaceDeclaration') {
+          continue;
+        }
+
+        for (const bodyItem of interfaceDeclaration.body.body) {
+          const methodSig = /** @type {import('@typescript-eslint/types').TSESTree.TSMethodSignature} */ (
+            bodyItem
+          );
+          if (methodName === /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
+            methodSig.key
+          ).name) {
+            return methodSig;
+          }
+        }
+      }
+    }
+
+    scp = scp.upper;
+  }
+
+  return null;
+};
+
+/**
+ * @param {import('eslint').Rule.Node} node
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {import('../iterateJsdoc.js').Settings} settings
+ */
+const isExemptedImplementer = (node, sourceCode, context, settings) => {
+  if (node.type === 'FunctionExpression' &&
+    node.parent.type === 'MethodDefinition' &&
+    node.parent.parent.type === 'ClassBody' &&
+    node.parent.parent.parent.type === 'ClassDeclaration' &&
+    'implements' in node.parent.parent.parent
+  ) {
+    const implments = /** @type {import('@typescript-eslint/types').TSESTree.TSClassImplements[]} */ (
+      node.parent.parent.parent.implements
+    );
+
+    const {
+      name: methodName,
+    } = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
+      node.parent.key
+    );
+
+    for (const impl of implments) {
+      const {
+        name: interfaceName,
+      } = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
+        impl.expression
+      );
+
+      const interfaceMethodNode = getMethodOnInterface(interfaceName, methodName, node && (
+        (sourceCode.getScope &&
+        /* c8 ignore next 2 */
+        sourceCode.getScope(node)) ||
+        context.getScope()
+      ));
+      if (interfaceMethodNode) {
+        // @ts-expect-error Ok
+        const comment = getJSDocComment(sourceCode, interfaceMethodNode, settings);
+        if (comment) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+};
+
 /**
  * @param {import('eslint').Rule.RuleContext} context
  * @param {import('json-schema').JSONSchema4Object} baseObject
@@ -421,6 +515,10 @@ export default {
         }
       }
 
+      if (isExemptedImplementer(node, sourceCode, context, settings)) {
+        return;
+      }
+
       const fix = /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
         // Default to one line break if the `minLines`/`maxLines` settings allow
         const lines = settings.minLines === 0 && settings.maxLines >= 1 ? 1 : settings.minLines;

test/rules/assertions/requireJsdoc.js

@@ -4251,6 +4251,51 @@ function quux (foo) {
         export type { Props as ComponentProps };
       `,
     },
+    {
+      code: `
+        export interface A {
+          a: string;
+        }
+
+        export class B implements A, B {
+          a = 'abc';
+          public f(): void {
+            //
+          }
+        }
+      `,
+      errors: [
+        {
+          line: 8,
+          message: 'Missing JSDoc comment.',
+        },
+      ],
+      languageOptions: {
+        parser: typescriptEslintParser,
+      },
+      options: [
+        {
+          contexts: [
+            'MethodDefinition',
+          ],
+        },
+      ],
+      output: `
+        export interface A {
+          a: string;
+        }
+
+        export class B implements A, B {
+          a = 'abc';
+          /**
+           *
+           */
+          public f(): void {
+            //
+          }
+        }
+      `,
+    },
   ],
   valid: [
     {
@@ -6398,5 +6443,33 @@ function quux (foo) {
         parser: typescriptEslintParser,
       },
     },
+    {
+      code: `
+        export interface A {
+          a: string;
+          /**
+           * Documentation.
+           */
+          f(): void;
+        }
+
+        export class B implements A {
+          a = 'abc';
+          public f(): void {
+            //
+          }
+        }
+      `,
+      languageOptions: {
+        parser: typescriptEslintParser,
+      },
+      options: [
+        {
+          contexts: [
+            'MethodDefinition',
+          ],
+        },
+      ],
+    },
   ],
 });