ESLint rule – required jsdoc comment for public methods, getters and setters

README.md

jsdoc-for-public

This rule enforces writing JSDoc comments for public methods, getters, and setters. By default, it operates throughout the entire project.

Optionally, it accepts the following arguments:

• excluded - an array of files/folders to exclude.
• description - additional description of the rule (e.g., a link to Confluence).

{
  "jsdoc-for-public": ["error", {
    excluded: ['src', 'pages'],
    description: 'Additional description'
  }],
}

jsdoc-for-public.js

/* eslint-disable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/restrict-template-expressions, @typescript-eslint/no-unsafe-argument */
const path = require("path");

/**
 * Each comment must start with a /** sequence in order to be recognized by the JSDoc parser. Comments beginning with /*, /***, or more than 3 stars will be ignored.
 * See: https://jsdoc.app/about-getting-started
 */
const JSDOC_TAG = "*";

/**
 * Filter for public methods, getters and setters
 */
const VALID_NODE_KINDS = ["method", "get", "set"];

module.exports = {
  meta: {
    type: "suggestion",
    docs: {
      description:
        "Required JSDoc for public methods, getters and setters.",
    },
    schema: [
      {
        type: "object",
        properties: {
          excluded: {
            type: "array",
            items: { type: "string" },
          },
          description: {
            type: "string",
          },
        },
        additionalProperties: false,
      },
    ],
  },
  create(context) {
    // List of files/folders to exclude from the rule
    const options = context.options[0] || {};
    const excludedPatterns = options.excluded || [];
    const EXCLUDED = excludedPatterns.map((pattern) => path.resolve(pattern));

    // Additional info about the rule from the options
    const description = context.options[0]?.description || "";

    return {
      MethodDefinition(node) {
        const currentFilePath = context.getFilename();
        const filePath = path.resolve(currentFilePath);

        const isExcluded = EXCLUDED.some((path) => filePath.startsWith(path));
        const isValidNodeKind = VALID_NODE_KINDS.includes(node.kind);
        const isPublic = node.accessibility !== "private";

        if (!isExcluded && isValidNodeKind && isPublic) {
          const comments = context.getCommentsBefore(node) || [];

          // Block has jsdoc comment
          const hasJsDocComment = comments.some((comment) => {
            return (
              comment.type === "Block" && comment.value.startsWith(JSDOC_TAG)
            );
          });

          // If there is no comment, display a error
          if (!hasJsDocComment) {
            context.report({
              node,
              message: `Public methods, getters and setters must have JSDoc comment. ${description}`,
            });
          }
        }
      },
    };
  },
};