Code Quality: Relax JSDoc validation for typed packages (#28729)

.eslintrc.js

@@ -2,6 +2,8 @@
  * External dependencies
  */
 const { escapeRegExp } = require( 'lodash' );
+const glob = require( 'glob' ).sync;
+const { join } = require( 'path' );
 
 /**
  * Internal dependencies
@@ -28,6 +30,11 @@ const developmentFiles = [
 	'**/@(storybook|stories)/**/*.js',
 ];
 
+// All files from packages that have types provided with TypeScript.
+const typedFiles = glob( 'packages/*/package.json' )
+	.filter( ( fileName ) => require( join( __dirname, fileName ) ).types )
+	.map( ( fileName ) => fileName.replace( 'package.json', '**/*.js' ) );
+
 module.exports = {
 	root: true,
 	extends: [
@@ -202,5 +209,12 @@ module.exports = {
 				'no-console': 'off',
 			},
 		},
+		{
+			files: typedFiles,
+			rules: {
+				'jsdoc/no-undefined-types': 'off',
+				'jsdoc/valid-types': 'off',
+			},
+		},
 	],
 };

packages/components/src/ui/utils/create-component.js

@@ -9,14 +9,14 @@ import { identity } from 'lodash';
  */
 import { View } from '../view';
 
-/* eslint-disable jsdoc/require-returns-description */
 /**
+ * Factory that creates a React component.
+ *
  * @template {import('reakit-utils/types').As} T
  * @template {import('@wp-g2/create-styles').ViewOwnProps<{}, T>} P
- * @param {import('./types').Options<T, P>} options
- * @return {import('@wp-g2/create-styles').PolymorphicComponent<T, import('@wp-g2/create-styles').PropsFromViewOwnProps<P>>}
+ * @param {import('./types').Options<T, P>} options Options to customize the component.
+ * @return {import('@wp-g2/create-styles').PolymorphicComponent<T, import('@wp-g2/create-styles').PropsFromViewOwnProps<P>>} New React component.
  */
-/* eslint-enable jsdoc/require-returns-description */
 /* eslint-disable jsdoc/no-undefined-types */
 export const createComponent = ( {
 	as,

packages/i18n/src/create-i18n.js

@@ -22,7 +22,6 @@ const DEFAULT_LOCALE_DATA = {
 	},
 };
 
-/* eslint-disable jsdoc/valid-types */
 /**
  * @typedef {(data?: LocaleData, domain?: string) => void} SetLocaleData
  * Merges locale data into the Tannin instance by domain. Accepts data in a
@@ -77,7 +76,6 @@ const DEFAULT_LOCALE_DATA = {
 /**
  * @typedef {{ applyFilters: (hookName:string, ...args: unknown[]) => unknown}} ApplyFiltersInterface
  */
-/* eslint-enable jsdoc/valid-types */
 
 /**
  * An i18n instance

packages/keycodes/src/index.js

@@ -37,14 +37,12 @@ import { isAppleOS } from './platform';
  * @typedef {Record<WPKeycodeModifier, T>} WPModifierHandler
  */
 
-/* eslint-disable jsdoc/valid-types */
 /**
  * @template T
  *
  * @typedef {(character: string, isApple?: () => boolean) => T} WPKeyHandler
  */
 /** @typedef {(event: KeyboardEvent, character: string, isApple?: () => boolean) => boolean} WPEventKeyHandler */
-/* eslint-enable jsdoc/valid-types */
 
 /**
  * Keycode for BACKSPACE key.

packages/token-list/src/index.js

@@ -27,9 +27,6 @@ export default class TokenList {
 		/* eslint-enable no-unused-expressions */
 	}
 
-	// Disable reason: JSDoc lint doesn't understand TypeScript types
-	/* eslint-disable jsdoc/valid-types */
-
 	/**
 	 * @param {Parameters<Array<string>['entries']>} args
 	 */
@@ -58,8 +55,6 @@ export default class TokenList {
 		return this._valueAsArray.values( ...args );
 	}
 
-	/* eslint-enable jsdoc/valid-types */
-
 	/**
 	 * Returns the associated set as string.
 	 *

packages/url/src/get-query-arg.js

@@ -3,11 +3,9 @@
  */
 import { getQueryArgs } from './get-query-args';
 
-/* eslint-disable jsdoc/valid-types */
 /**
  * @typedef {{[key: string]: QueryArgParsed}} QueryArgObject
  */
-/* eslint-enable */
 
 /**
  * @typedef {string|string[]|QueryArgObject} QueryArgParsed