meta: Eslint JSDoc plugin (#147)

Author: canerakdas

eslint.config.mjs

@@ -1,12 +1,43 @@
 import pluginJs from '@eslint/js';
 import eslintConfigPrettier from 'eslint-config-prettier';
+import jsdoc from 'eslint-plugin-jsdoc';
 import globals from 'globals';
 
 export default [
   // @see https://eslint.org/docs/latest/use/configure/configuration-files#specifying-files-and-ignores
   {
     files: ['src/**/*.mjs'],
+    plugins: {
+      jsdoc: jsdoc,
+    },
     languageOptions: { globals: globals.node },
+    rules: {
+      'jsdoc/check-alignment': 'error',
+      'jsdoc/check-indentation': 'error',
+      'jsdoc/require-jsdoc': [
+        'error',
+        {
+          require: {
+            FunctionDeclaration: true,
+            MethodDefinition: true,
+            ClassDeclaration: true,
+            ArrowFunctionExpression: true,
+            FunctionExpression: true,
+          },
+        },
+      ],
+      'jsdoc/require-param': 'error',
+    },
+  },
+  // Override rules for test files to disable JSDoc rules
+  {
+    files: ['src/**/*.test.mjs'],
+    rules: {
+      'jsdoc/check-alignment': 'off',
+      'jsdoc/check-indentation': 'off',
+      'jsdoc/require-jsdoc': 'off',
+      'jsdoc/require-param': 'off',
+    },
   },
   // @see https://eslint.org/docs/latest/use/configure/configuration-files#specifying-files-and-ignores
   {

package-lock.json

@@ -21,6 +21,7 @@
     "@types/node": "^22.9.0",
     "eslint": "^9.13.0",
     "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-jsdoc": "^50.5.0",
     "globals": "^15.11.0",
     "husky": "^9.1.6",
     "lint-staged": "^15.2.10",

package.json

@@ -29,6 +29,11 @@ export default {
 
   dependsOn: 'ast',
 
+  /**
+   * Generates the simplified JSON version of the API docs
+   * @param {Input} input
+   * @param {Partial<GeneratorOptions>} options
+   */
   async generate(input, options) {
     // Gets a remark processor for stringifying the AST tree into JSON
     const remarkProcessor = getRemark();
@@ -45,7 +50,10 @@ export default {
         createQueries.UNIST.isHeading,
       ]);
 
-      // For the JSON generate we want to transform the whole content into JSON
+      /**
+       * For the JSON generate we want to transform the whole content into JSON
+       * @returns {string} The stringified JSON version of the content
+       */
       content.toJSON = () => remarkProcessor.stringify(content);
 
       return { ...node, content };

src/generators/json-simple/index.mjs

@@ -12,13 +12,13 @@ import { getRemarkRehype } from '../../utils/remark.mjs';
 
 /**
  * @typedef {{
- *  api: string;
- *  added: string;
- *  section: string;
- *  version: string;
- *  toc: string;
- *  nav: string;
- *  content: string;
+ * api: string;
+ * added: string;
+ * section: string;
+ * version: string;
+ * toc: string;
+ * nav: string;
+ * content: string;
  * }} TemplateValues
  *
  * This generator generates the legacy HTML pages of the legacy API docs
@@ -41,6 +41,11 @@ export default {
 
   dependsOn: 'legacy-html',
 
+  /**
+   * Generates the `all.html` file from the `legacy-html` generator
+   * @param {Input} input
+   * @param {Partial<GeneratorOptions>} options
+   */
   async generate(input, { version, releases, output }) {
     const inputWithoutIndex = input.filter(entry => entry.api !== 'index');
 

src/generators/legacy-html-all/index.mjs

@@ -14,13 +14,13 @@ import { getRemarkRehype } from '../../utils/remark.mjs';
 
 /**
  * @typedef {{
- *  api: string;
- *  added: string;
- *  section: string;
- *  version: string;
- *  toc: string;
- *  nav: string;
- *  content: string;
+ * api: string;
+ * added: string;
+ * section: string;
+ * version: string;
+ * toc: string;
+ * nav: string;
+ * content: string;
  * }} TemplateValues
  *
  * This generator generates the legacy HTML pages of the legacy API docs
@@ -43,6 +43,11 @@ export default {
 
   dependsOn: 'ast',
 
+  /**
+   * Generates the legacy version of the API docs in HTML
+   * @param {Input} input
+   * @param {Partial<GeneratorOptions>} options
+   */
   async generate(input, { releases, version, output }) {
     // This array holds all the generated values for each module
     const generatedValues = [];