From 33389797eeb9abf52fb884bb6e433486ab596d57 Mon Sep 17 00:00:00 2001 From: Andrea Fercia Date: Sat, 22 Aug 2026 09:32:28 +0200 Subject: [PATCH 1/3] Fix lint:jsdoc with full new rules configuration. --- .eslintrc-jsdoc.js | 41 ++++++++++++----------------------------- eslint.config.js | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 29 deletions(-) create mode 100644 eslint.config.js diff --git a/.eslintrc-jsdoc.js b/.eslintrc-jsdoc.js index 6f7351ec08945..17bef00d49dd5 100644 --- a/.eslintrc-jsdoc.js +++ b/.eslintrc-jsdoc.js @@ -1,29 +1,12 @@ -module.exports = { - rules: { - 'require-jsdoc': 'off', - 'valid-jsdoc': [ 'error', { - prefer: { - arg: 'param', - argument: 'param', - extends: 'augments', - returns: 'return', - }, - preferType: { - array: 'Array', - bool: 'boolean', - Boolean: 'boolean', - float: 'number', - Float: 'number', - int: 'number', - integer: 'number', - Integer: 'number', - Number: 'number', - object: 'Object', - String: 'string', - Void: 'void', - }, - requireParamDescription: false, - requireReturn: false, - } ], - }, -}; +/** + * ESLint v10 flat config file for JSDoc linting. + * + * This file contains JSDoc validation rules converted to ESLint v10's + * flat config format. It can be used standalone or imported by eslint.config.js. + */ + +const wordpressPlugin = require( '@wordpress/eslint-plugin' ); + +module.exports = [ + ...wordpressPlugin.configs.jsdoc, +]; diff --git a/eslint.config.js b/eslint.config.js new file mode 100644 index 0000000000000..a3f2f384d7d7b --- /dev/null +++ b/eslint.config.js @@ -0,0 +1,38 @@ +/** + * ESLint v10 flat config entry point. + * + * This minimal config focuses only on JSDoc linting by importing + * the configuration from .eslintrc-jsdoc.js. + * + * General JavaScript linting is not performed here. + */ + +const jsdocConfig = require( './.eslintrc-jsdoc.js' ); + +module.exports = [ + ...jsdocConfig, + { + ignores: [ + 'build/**', + '**/build/**', + 'node_modules/**', + 'tests/**', + 'vendor/**', + 'tools/**', + 'jsdoc/**', + 'artifacts/**', + 'coverage/**', + '.cache/**', + 'src/wp-includes/blocks/**/*.js', + 'src/wp-includes/blocks/**/*.js.map', + 'src/wp-content/themes/**', + 'src/wp-content/plugins/**', + 'src/wp-content/mu-plugins/**', + 'src/wp-content/upgrade/**', + 'src/wp-content/uploads/**', + 'src/js/_enqueues/vendor/**', + 'src/wp-admin/js/**', + 'src/wp-includes/js/**', + ], + }, +]; From 97bf4e5caf9adc6c3312fae339f75d90ca81e52c Mon Sep 17 00:00:00 2001 From: Andrea Fercia Date: Sat, 22 Aug 2026 10:06:07 +0200 Subject: [PATCH 2/3] Use minimal ruleset. --- .eslintrc-jsdoc.js | 81 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 76 insertions(+), 5 deletions(-) diff --git a/.eslintrc-jsdoc.js b/.eslintrc-jsdoc.js index 17bef00d49dd5..39604644eb9a4 100644 --- a/.eslintrc-jsdoc.js +++ b/.eslintrc-jsdoc.js @@ -1,12 +1,83 @@ /** * ESLint v10 flat config file for JSDoc linting. - * - * This file contains JSDoc validation rules converted to ESLint v10's - * flat config format. It can be used standalone or imported by eslint.config.js. + * This config is based on the original valid-jsdoc rules. */ -const wordpressPlugin = require( '@wordpress/eslint-plugin' ); +const jsdocPlugin = require( 'eslint-plugin-jsdoc' ); module.exports = [ - ...wordpressPlugin.configs.jsdoc, + { + plugins: { + jsdoc: jsdocPlugin, + }, + rules: { + // JSDoc validation - matching original valid-jsdoc behavior + + // Validate @param names match actual function parameters + 'jsdoc/check-param-names': 'error', + + // Type validation with exemptTagContexts to allow flexible type formats + // This avoids enforcing type normalization (Object→object) preferences + 'jsdoc/check-types': [ 'error', { + noDefaults: true, + exemptTagContexts: [ + { tag: 'param', types: true }, + { tag: 'return', types: true }, + { tag: 'returns', types: true }, + { tag: 'type', types: true }, + { tag: 'typedef', types: true }, + { tag: 'property', types: true }, + { tag: 'arg', types: true }, + { tag: 'argument', types: true }, + ], + } ], + + // NOTE: check-tag-names is DISABLED because eslint-plugin-jsdoc enforces + // opposite tag preferences (return→returns) than the original valid-jsdoc + // (which preferred returns→return). Disabling avoids ~1600 false positives. + 'jsdoc/check-tag-names': 'off', + + // Disable all other jsdoc rules to match minimal original requirements + 'jsdoc/check-indentation': 'off', + 'jsdoc/check-line-alignment': 'off', + 'jsdoc/check-property-names': 'off', + 'jsdoc/check-syntax': 'off', + 'jsdoc/check-template-names': 'off', + 'jsdoc/check-values': 'off', + 'jsdoc/convert-to-jsdoc-comments': 'off', + 'jsdoc/empty-tags': 'off', + 'jsdoc/implements-on-classes': 'off', + 'jsdoc/match-description': 'off', + 'jsdoc/multiline-blocks': 'off', + 'jsdoc/no-bad-blocks': 'off', + 'jsdoc/no-defaults': 'off', + 'jsdoc/no-types': 'off', + 'jsdoc/require-asterisk-prefix': 'off', + 'jsdoc/require-description': 'off', + 'jsdoc/require-description-complete-sentence': 'off', + 'jsdoc/require-example': 'off', + 'jsdoc/require-file-overview': 'off', + 'jsdoc/require-hyphen-before-param-description': 'off', + 'jsdoc/require-jsdoc': 'off', + 'jsdoc/require-param': 'off', + 'jsdoc/require-param-description': 'off', + 'jsdoc/require-param-name': 'off', + 'jsdoc/require-param-type': 'off', + 'jsdoc/require-property': 'off', + 'jsdoc/require-property-description': 'off', + 'jsdoc/require-property-name': 'off', + 'jsdoc/require-property-type': 'off', + 'jsdoc/require-returns': 'off', + 'jsdoc/require-returns-check': 'off', + 'jsdoc/require-returns-description': 'off', + 'jsdoc/require-returns-type': 'off', + 'jsdoc/require-throws': 'off', + 'jsdoc/require-yields': 'off', + 'jsdoc/require-yields-check': 'off', + 'jsdoc/sort-tags': 'off', + 'jsdoc/tag-lines': 'off', + 'jsdoc/text-escaping': 'off', + 'jsdoc/valid-types': 'off', + }, + }, ]; From e555afc8c353649c505dcc97b3ff5ae0f6d7134b Mon Sep 17 00:00:00 2001 From: Andrea Fercia Date: Sat, 22 Aug 2026 10:07:13 +0200 Subject: [PATCH 3/3] Remove no longer necessary .eslintignore file. --- .eslintignore | 26 -------------------------- 1 file changed, 26 deletions(-) delete mode 100644 .eslintignore diff --git a/.eslintignore b/.eslintignore deleted file mode 100644 index 9b3144df5c64d..0000000000000 --- a/.eslintignore +++ /dev/null @@ -1,26 +0,0 @@ -# Files and folders related to build/test tools including generated files -/build -/node_modules -/tests -/vendor -/tools -/jsdoc -/artifacts -/coverage -.cache/* -/src/wp-includes/blocks/**/*.js -/src/wp-includes/blocks/**/*.js.map -/src/wp-admin/js -/src/wp-includes/js - -# Excluded files and folders based on `jsdoc.conf.json` exclusions -/src/js/_enqueues/vendor - -# Themes -src/wp-content/themes - -# Files and folders that get created in wp-content -/src/wp-content/plugins -/src/wp-content/mu-plugins -/src/wp-content/upgrade -/src/wp-content/uploads