Enable ESLint JSDoc checks

.eslintrc.js

@@ -13,6 +13,7 @@ module.exports = {
       extends: [
         'eslint:recommended',
         'plugin:import/recommended',
+        'plugin:jsdoc/recommended-typescript-flavor',
         'plugin:n/recommended',
         'plugin:promise/recommended',
         'prettier'
@@ -27,7 +28,7 @@ module.exports = {
       parserOptions: {
         ecmaVersion: 'latest'
       },
-      plugins: ['import', 'n', 'promise'],
+      plugins: ['import', 'jsdoc', 'n', 'promise'],
       rules: {
         // Check import or require statements are A-Z ordered
         'import/order': [
@@ -38,9 +39,48 @@ module.exports = {
           }
         ],
 
+        // JSDoc blocks are optional by default
+        'jsdoc/require-jsdoc': 'off',
+
+        // Check for valid formatting
+        'jsdoc/check-line-alignment': [
+          'warn',
+          'never',
+          {
+            wrapIndent: '  '
+          }
+        ],
+
+        // Add unknown @jest-environment tag name
+        'jsdoc/check-tag-names': [
+          'warn',
+          {
+            definedTags: ['jest-environment']
+          }
+        ],
+
+        // Require hyphens before param description
+        // Aligns with TSDoc style: https://tsdoc.org/pages/tags/param/
+        'jsdoc/require-hyphen-before-param-description': 'warn',
+
+        // Maintain new line after description
+        'jsdoc/tag-lines': [
+          'warn',
+          'never',
+          {
+            startLines: 1
+          }
+        ],
+
         // Automatically use template strings
         'no-useless-concat': 'error',
         'prefer-template': 'error'
+      },
+      settings: {
+        jsdoc: {
+          // Allows us to use type declarations that exist in our dependencies
+          mode: 'typescript'
+        }
       }
     },
     {

package.json

@@ -57,6 +57,7 @@
     "eslint-config-prettier": "^9.0.0",
     "eslint-config-standard": "^17.0.0",
     "eslint-plugin-import": "^2.29.0",
+    "eslint-plugin-jsdoc": "^46.9.0",
     "eslint-plugin-markdown": "^3.0.1",
     "eslint-plugin-n": "^16.3.1",
     "eslint-plugin-promise": "^6.1.1",

src/.eslintrc.js

@@ -11,7 +11,27 @@ module.exports = {
         // Note: Allow ES2015 for import/export syntax
         ecmaVersion: '2015'
       },
-      plugins: ['es-x']
+      plugins: ['es-x'],
+      rules: {
+        // JSDoc blocks are mandatory in source code
+        'jsdoc/require-jsdoc': [
+          'error',
+          {
+            enableFixer: false,
+            require: {
+              ClassDeclaration: true,
+              ClassExpression: true,
+              FunctionExpression: true,
+              MethodDefinition: true
+            }
+          }
+        ],
+
+        // JSDoc @param required in (mandatory) blocks but
+        // @param description is necessary in source code
+        'jsdoc/require-param-description': 'warn',
+        'jsdoc/require-param': 'error'
+      }
     }
   ]
 }