tools: use jsdoc recommended rules

Enable all recommended JSDoc linting rules and disable the ones we don't
(yet?) meet. They can be enabled one by one by removing the lines that
turn them off.

This requires adding --max-warnings to the ESLint invocations in
Makefile and vcbuild.bat because the preset enables the recommended
rules as warnings and not errors.

PR-URL: #41057
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

.eslintrc.js

@@ -35,6 +35,7 @@ Module._findPath = (request, paths, isMain) => {
 
 module.exports = {
   root: true,
+  extends: ['plugin:jsdoc/recommended'],
   plugins: ['jsdoc', 'markdown', 'node-core'],
   parser: '@babel/eslint-parser',
   parserOptions: {
@@ -338,7 +339,22 @@ module.exports = {
     'valid-typeof': ['error', { requireStringLiterals: true }],
 
     // JSDoc rules
-    'jsdoc/check-types': 'error',
+    'jsdoc/require-jsdoc': 'off',
+    'jsdoc/require-param-description': 'off',
+    'jsdoc/newline-after-description': 'off',
+    'jsdoc/require-returns-description': 'off',
+    'jsdoc/valid-types': 'off',
+    'jsdoc/no-undefined-types': 'off',
+    'jsdoc/require-param': 'off',
+    'jsdoc/check-tag-names': 'off',
+    'jsdoc/require-returns': 'off',
+    'jsdoc/require-property-description': 'off',
+    'jsdoc/check-param-names': 'off',
+    'jsdoc/tag-lines': 'off',
+    'jsdoc/require-returns-type': 'off',
+    'jsdoc/check-alignment': 'off',
+    'jsdoc/require-returns-check': 'off',
+    'jsdoc/require-param-name': 'off',
 
     // Custom rules from eslint-plugin-node-core
     'node-core/no-unescaped-regexp-dot': 'error',

Makefile

@@ -1268,7 +1268,7 @@ format-md:
 LINT_JS_TARGETS = .eslintrc.js benchmark doc lib test tools
 
 run-lint-js = tools/node_modules/eslint/bin/eslint.js --cache \
-	--report-unused-disable-directives $(LINT_JS_TARGETS)
+	--max-warnings=0 --report-unused-disable-directives $(LINT_JS_TARGETS)
 run-lint-js-fix = $(run-lint-js) --fix
 
 .PHONY: lint-js-fix
@@ -1292,7 +1292,7 @@ jslint: lint-js
 	$(warning Please use lint-js instead of jslint)
 
 run-lint-js-ci = tools/node_modules/eslint/bin/eslint.js \
-  --report-unused-disable-directives -f tap \
+  --max-warnings=0 --report-unused-disable-directives -f tap \
 	-o test-eslint.tap $(LINT_JS_TARGETS)
 
 .PHONY: lint-js-ci

vcbuild.bat

@@ -699,7 +699,7 @@ goto lint-js
 if not defined lint_js goto lint-md-build
 if not exist tools\node_modules\eslint goto no-lint
 echo running lint-js
-%node_exe% tools\node_modules\eslint\bin\eslint.js --cache --report-unused-disable-directives --rule "linebreak-style: 0" .eslintrc.js benchmark doc lib test tools
+%node_exe% tools\node_modules\eslint\bin\eslint.js --cache --max-warnings=0 --report-unused-disable-directives --rule "linebreak-style: 0" .eslintrc.js benchmark doc lib test tools
 goto lint-md-build
 
 :no-lint