Fix(eslint-plugin): misc bugfixes related to recent jsdoc changes (#1…

…6975) * fix(eslint-plugin): misc assorted fixes to jsdoc config * fix: misc jsdoc fixes * remove duplicate Readonly
WordPress · Aug 29, 2019 · fa3cddb · fa3cddb
1 parent 7ca7763
commit fa3cddb
Show file tree

Hide file tree

Showing 9 changed files with 45 additions and 10 deletions.
diff --git a/docs/designers-developers/developers/data/data-core.md b/docs/designers-developers/developers/data/data-core.md
@@ -373,7 +373,7 @@ _Parameters_
 
 _Returns_
 
--   `booleans`: Is the preview for the URL an oEmbed link fallback.
+-   `boolean`: Is the preview for the URL an oEmbed link fallback.
 
 <a name="isRequestingEmbedPreview" href="#isRequestingEmbedPreview">#</a> **isRequestingEmbedPreview**
 

diff --git a/packages/block-editor/src/components/inserter/index.native.js b/packages/block-editor/src/components/inserter/index.native.js
@@ -45,6 +45,7 @@ class Inserter extends Component {
 	/**
 	 * Render callback to display Dropdown toggle element.
 	 *
+	 * @param {Object}   options
 	 * @param {Function} options.onToggle Callback to invoke when toggle is
 	 *                                    pressed.
 	 * @param {boolean}  options.isOpen   Whether dropdown is currently open.
@@ -63,6 +64,7 @@ class Inserter extends Component {
 	/**
 	 * Render callback to display Dropdown content element.
 	 *
+	 * @param {Object}   options
 	 * @param {Function} options.onClose Callback to invoke when dropdown is
 	 *                                   closed.
 	 *

diff --git a/packages/components/src/tooltip/index.js b/packages/components/src/tooltip/index.js
@@ -117,7 +117,7 @@ class Tooltip extends Component {
 	 * Creates an event callback to handle assignment of the `isInMouseDown`
 	 * instance property in response to a `mousedown` or `mouseup` event.
 	 *
-	 * @param {booelan} isMouseDown Whether handler is to be created for the
+	 * @param {boolean} isMouseDown Whether handler is to be created for the
 	 *                              `mousedown` event, as opposed to `mouseup`.
 	 *
 	 * @return {Function} Event callback handler.

diff --git a/packages/core-data/README.md b/packages/core-data/README.md
@@ -584,7 +584,7 @@ _Parameters_
 
 _Returns_
 
--   `booleans`: Is the preview for the URL an oEmbed link fallback.
+-   `boolean`: Is the preview for the URL an oEmbed link fallback.
 
 <a name="isRequestingEmbedPreview" href="#isRequestingEmbedPreview">#</a> **isRequestingEmbedPreview**
 

diff --git a/packages/core-data/src/selectors.js b/packages/core-data/src/selectors.js
@@ -355,7 +355,7 @@ export function getEmbedPreview( state, url ) {
  * @param {Object} state    Data state.
  * @param {string} url      Embedded URL.
  *
- * @return {booleans} Is the preview for the URL an oEmbed link fallback.
+ * @return {boolean} Is the preview for the URL an oEmbed link fallback.
  */
 export function isPreviewEmbedFallback( state, url ) {
 	const preview = state.embedPreviews[ url ];

diff --git a/packages/eslint-plugin/configs/es5.js b/packages/eslint-plugin/configs/es5.js
@@ -1,4 +1,7 @@
 module.exports = {
+	extends: [
+		require.resolve( './jsdoc.js' ),
+	],
 	rules: {
 		'array-bracket-spacing': [ 'error', 'always' ],
 		'array-callback-return': 'error',

diff --git a/packages/eslint-plugin/configs/jsdoc.js b/packages/eslint-plugin/configs/jsdoc.js
@@ -1,5 +1,32 @@
 const globals = require( 'globals' );
 
+/**
+ * Helpful utilities that are globally defined and known to the TypeScript compiler.
+ *
+ * @see http://www.typescriptlang.org/docs/handbook/utility-types.html
+ */
+const typescriptUtilityTypes = [
+	'ArrayLike',
+	'Exclude',
+	'Extract',
+	'InstanceType',
+	'Iterable',
+	'IterableIterator',
+	'NonNullable',
+	'Omit',
+	'Partial',
+	'Pick',
+	'PromiseLike',
+	'Readonly',
+	'ReadonlyArray',
+	'ReadonlyMap',
+	'ReadonlySet',
+	'Record',
+	'Required',
+	'ReturnType',
+	'ThisType',
+];
+
 module.exports = {
 	extends: [
 		'plugin:jsdoc/recommended',
@@ -17,10 +44,14 @@ module.exports = {
 	},
 	rules: {
 		'jsdoc/no-undefined-types': [ 'warn', {
-			// Required to reference browser types because we don't have the `browser` environment enabled for the project.
-			// Here we filter out all browser globals that don't begin with an uppercase letter because those
-			// generally refer to window-level event listeners and are not a valid type to reference (e.g. `onclick`).
-			definedTypes: Object.keys( globals.browser ).filter( ( k ) => /^[A-Z]/.test( k ) ),
+			definedTypes: [
+				// Required to reference browser types because we don't have the `browser` environment enabled for the project.
+				// Here we filter out all browser globals that don't begin with an uppercase letter because those
+				// generally refer to window-level event listeners and are not a valid type to reference (e.g. `onclick`).
+				...Object.keys( globals.browser ).filter( ( k ) => /^[A-Z]/.test( k ) ),
+				...typescriptUtilityTypes,
+				'void',
+			],
 		} ],
 		'jsdoc/require-jsdoc': 'off',
 		'jsdoc/require-param-description': 'off',

diff --git a/packages/eslint-plugin/configs/recommended.js b/packages/eslint-plugin/configs/recommended.js
@@ -5,7 +5,6 @@ module.exports = {
 		require.resolve( './custom.js' ),
 		require.resolve( './react.js' ),
 		require.resolve( './esnext.js' ),
-		require.resolve( './jsdoc.js' ),
 	],
 	env: {
 		node: true,

diff --git a/packages/token-list/src/index.js b/packages/token-list/src/index.js
@@ -76,7 +76,7 @@ export default class TokenList {
 	 *
 	 * @see https://dom.spec.whatwg.org/#domtokenlist
 	 *
-	 * @return {Generator} TokenList iterator.
+	 * @return {IterableIterator<string>} TokenList iterator.
 	 */
 	* [ Symbol.iterator ]() {
 		return yield* this._valueAsArray;