fix all JSDoc eslint errors/warnings across the entire repository (#1…

…6870)

* chore: fix all JSDoc eslint errors/warnings across the entire repository

* fix: address code review comments

bin/commander.js

@@ -57,7 +57,7 @@ async function askForConfirmationToContinue( message, isDefault = true, abortMes
  *
  * @param {string} name         Step name.
  * @param {string} abortMessage Abort message.
- * @param {function} handler    Step logic.
+ * @param {Function} handler    Step logic.
  */
 async function runStep( name, abortMessage, handler ) {
 	try {

docs/designers-developers/developers/data/data-core-block-editor.md

@@ -203,7 +203,7 @@ on each call
 _Parameters_
 
 -   _state_ `Object`: Editor state.
--   _rootClientId_ `?String`: Optional root client ID of block list.
+-   _rootClientId_ `?string`: Optional root client ID of block list.
 
 _Returns_
 
@@ -299,7 +299,7 @@ The number returned includes nested blocks.
 _Parameters_
 
 -   _state_ `Object`: Global application state.
--   _blockName_ `?String`: Optional block name, if specified only blocks of that type will be counted.
+-   _blockName_ `?string`: Optional block name, if specified only blocks of that type will be counted.
 
 _Returns_
 

packages/annotations/src/format/annotation.js

@@ -92,10 +92,11 @@ function retrieveAnnotationPositions( formats ) {
 /**
  * Updates annotations in the state based on positions retrieved from RichText.
  *
- * @param {Array}    annotations           The annotations that are currently applied.
- * @param {Array}    positions             The current positions of the given annotations.
- * @param {Function} removeAnnotation      Function to remove an annotation from the state.
- * @param {Function} updateAnnotationRange Function to update an annotation range in the state.
+ * @param {Array}    annotations                   The annotations that are currently applied.
+ * @param {Array}    positions                     The current positions of the given annotations.
+ * @param {Object}   actions
+ * @param {Function} actions.removeAnnotation      Function to remove an annotation from the state.
+ * @param {Function} actions.updateAnnotationRange Function to update an annotation range in the state.
  */
 function updateAnnotationsWithPositions( annotations, positions, { removeAnnotation, updateAnnotationRange } ) {
 	annotations.forEach( ( currentAnnotation ) => {

packages/annotations/src/store/actions.js

@@ -13,16 +13,15 @@ import uuid from 'uuid/v4';
  *
  * The `range` property is only relevant if the selector is 'range'.
  *
- * @param {Object} annotation         The annotation to add.
- * @param {string} blockClientId      The blockClientId to add the annotation to.
- * @param {string} richTextIdentifier Identifier for the RichText instance the annotation applies to.
- * @param {Object} range              The range at which to apply this annotation.
- * @param {number} range.start        The offset where the annotation should start.
- * @param {number} range.end          The offset where the annotation should end.
- * @param {string} [selector="range"] The way to apply this annotation.
- * @param {string} [source="default"] The source that added the annotation.
- * @param {string} [id=uuid()]        The ID the annotation should have.
- *                                    Generates a UUID by default.
+ * @param {Object} annotation                    The annotation to add.
+ * @param {string} annotation.blockClientId      The blockClientId to add the annotation to.
+ * @param {string} annotation.richTextIdentifier Identifier for the RichText instance the annotation applies to.
+ * @param {Object} annotation.range              The range at which to apply this annotation.
+ * @param {number} annotation.range.start        The offset where the annotation should start.
+ * @param {number} annotation.range.end          The offset where the annotation should end.
+ * @param {string} annotation.[selector="range"] The way to apply this annotation.
+ * @param {string} annotation.[source="default"] The source that added the annotation.
+ * @param {string} annotation.[id]               The ID the annotation should have. Generates a UUID by default.
  *
  * @return {Object} Action object.
  */

packages/autop/src/index.js

@@ -1,7 +1,7 @@
 /**
  * The regular expression for an HTML element.
  *
- * @type {String}
+ * @type {string}
  */
 const htmlSplitRegex = ( () => {
 	/* eslint-disable no-multi-spaces */

packages/block-editor/README.md

@@ -456,7 +456,7 @@ export default compose(
 
 _Parameters_
 
--   _colorTypes_ `...(object|string)`: The arguments can be strings or objects. If the argument is an object, it should contain the color attribute name as key and the color context as value. If the argument is a string the value should be the color attribute name, the color context is computed by applying a kebab case transform to the value. Color context represents the context/place where the color is going to be used. The class name of the color is generated using 'has' followed by the color name and ending with the color context all in kebab case e.g: has-green-background-color.
+-   _colorTypes_ `...(Object|string)`: The arguments can be strings or objects. If the argument is an object, it should contain the color attribute name as key and the color context as value. If the argument is a string the value should be the color attribute name, the color context is computed by applying a kebab case transform to the value. Color context represents the context/place where the color is going to be used. The class name of the color is generated using 'has' followed by the color name and ending with the color context all in kebab case e.g: has-green-background-color.
 
 _Returns_
 
@@ -469,7 +469,7 @@ font size value retrieval, and font size change handling.
 
 _Parameters_
 
--   _args_ `...(object|string)`: The arguments should all be strings Each string contains the font size attribute name e.g: 'fontSize'.
+-   _fontSizeNames_ `...(Object|string)`: The arguments should all be strings. Each string contains the font size attribute name e.g: 'fontSize'.
 
 _Returns_
 

packages/block-editor/src/components/block-list/index.js

@@ -87,8 +87,6 @@ class BlockList extends Component {
 	 * multi-selection.
 	 *
 	 * @param {MouseEvent} event A mousemove event object.
-	 *
-	 * @return {void}
 	 */
 	onPointerMove( { clientY } ) {
 		// We don't start multi-selection until the mouse starts moving, so as
@@ -116,8 +114,6 @@ class BlockList extends Component {
 	 * in response to a mousedown event occurring in a rendered block.
 	 *
 	 * @param {string} clientId Client ID of block where mousedown occurred.
-	 *
-	 * @return {void}
 	 */
 	onSelectionStart( clientId ) {
 		if ( ! this.props.isSelectionEnabled ) {
@@ -173,8 +169,6 @@ class BlockList extends Component {
 
 	/**
 	 * Handles a mouseup event to end the current cursor multi-selection.
-	 *
-	 * @return {void}
 	 */
 	onSelectionEnd() {
 		// Cancel throttled calls.

packages/block-editor/src/components/block-title/index.js

@@ -14,6 +14,7 @@ import { getBlockType } from '@wordpress/blocks';
  * <BlockTitle clientId="afd1cb17-2c08-4e7a-91be-007ba7ddc3a1" />
  * ```
  *
+ * @param {Object}  props
  * @param {?string} props.name Block name.
  *
  * @return {?string} Block title.

packages/block-editor/src/components/colors/utils.js

@@ -30,14 +30,14 @@ export const getColorObjectByAttributeValues = ( colors, definedColor, customCol
 };
 
 /**
-* Provided an array of color objects as set by the theme or by the editor defaults, and a color value returns the color object matching that value or undefined.
-*
-* @param {Array}   colors      Array of color objects as set by the theme or by the editor defaults.
-* @param {?string} colorValue  A string containing the color value.
-*
-* @return {?Object} Color object included in the colors array whose color property equals colorValue.
-*                   Returns undefined if no color object matches this requirement.
-*/
+ * Provided an array of color objects as set by the theme or by the editor defaults, and a color value returns the color object matching that value or undefined.
+ *
+ * @param {Array}   colors      Array of color objects as set by the theme or by the editor defaults.
+ * @param {?string} colorValue  A string containing the color value.
+ *
+ * @return {?Object} Color object included in the colors array whose color property equals colorValue.
+ *                   Returns undefined if no color object matches this requirement.
+ */
 export const getColorObjectByColorValue = ( colors, colorValue ) => {
 	return find( colors, { color: colorValue } );
 };
@@ -60,13 +60,13 @@ export function getColorClassName( colorContextName, colorSlug ) {
 }
 
 /**
-* Given an array of color objects and a color value returns the color value of the most readable color in the array.
-*
-* @param {Array}   colors     Array of color objects as set by the theme or by the editor defaults.
-* @param {?string} colorValue A string containing the color value.
-*
-* @return {string} String with the color value of the most readable color.
-*/
+ * Given an array of color objects and a color value returns the color value of the most readable color in the array.
+ *
+ * @param {Array}   colors     Array of color objects as set by the theme or by the editor defaults.
+ * @param {?string} colorValue A string containing the color value.
+ *
+ * @return {string} String with the color value of the most readable color.
+ */
 export function getMostReadableColor( colors, colorValue ) {
 	return tinycolor.mostReadable(
 		colorValue,

packages/block-editor/src/components/colors/with-colors.js

@@ -23,7 +23,7 @@ const DEFAULT_COLORS = [];
  *
  * @param {Array} colorsArray An array of color objects.
  *
- * @return {function} The higher order component.
+ * @return {Function} The higher order component.
  */
 const withCustomColorPalette = ( colorsArray ) => createHigherOrderComponent( ( WrappedComponent ) => ( props ) => (
 	<WrappedComponent { ...props } colors={ colorsArray } />
@@ -33,7 +33,7 @@ const withCustomColorPalette = ( colorsArray ) => createHigherOrderComponent( (
  * Higher order component factory for injecting the editor colors as the
  * `colors` prop in the `withColors` HOC.
  *
- * @return {function} The higher order component.
+ * @return {Function} The higher order component.
  */
 const withEditorColorPalette = () => withSelect( ( select ) => {
 	const settings = select( 'core/block-editor' ).getSettings();
@@ -110,10 +110,10 @@ function createColorHOC( colorTypes, withColorPalette ) {
 						const previousColorObject = previousState[ colorAttributeName ];
 						const previousColor = get( previousColorObject, [ 'color' ] );
 						/**
-						* The "and previousColorObject" condition checks that a previous color object was already computed.
-						* At the start previousColorObject and colorValue are both equal to undefined
-						* bus as previousColorObject does not exist we should compute the object.
-						*/
+						 * The "and previousColorObject" condition checks that a previous color object was already computed.
+						 * At the start previousColorObject and colorValue are both equal to undefined
+						 * bus as previousColorObject does not exist we should compute the object.
+						 */
 						if ( previousColor === colorObject.color && previousColorObject ) {
 							newState[ colorAttributeName ] = previousColorObject;
 						} else {
@@ -187,7 +187,7 @@ export function createCustomColorsHOC( colorsArray ) {
  * );
  * ```
  *
- * @param {...(object|string)} colorTypes The arguments can be strings or objects. If the argument is an object,
+ * @param {...(Object|string)} colorTypes The arguments can be strings or objects. If the argument is an object,
  *                                        it should contain the color attribute name as key and the color context as value.
  *                                        If the argument is a string the value should be the color attribute name,
  *                                        the color context is computed by applying a kebab case transform to the value.

packages/block-editor/src/components/font-sizes/with-font-sizes.js

@@ -19,8 +19,9 @@ import { getFontSize, getFontSizeClass } from './utils';
  * Higher-order component, which handles font size logic for class generation,
  * font size value retrieval, and font size change handling.
  *
- * @param {...(object|string)} args The arguments should all be strings
- *                                  Each string contains the font size attribute name e.g: 'fontSize'.
+ * @param {...(Object|string)} fontSizeNames The arguments should all be strings.
+ *                                           Each string contains the font size
+ *                                           attribute name e.g: 'fontSize'.
  *
  * @return {Function} Higher-order component.
  */

packages/block-editor/src/components/ignore-nested-events/index.js

@@ -39,8 +39,6 @@ export class IgnoreNestedEvents extends Component {
 	 * it has not already been handled by a descendant IgnoreNestedEvents.
 	 *
 	 * @param {Event} event Event object.
-	 *
-	 * @return {void}
 	 */
 	proxyEvent( event ) {
 		const isHandled = !! event.nativeEvent._blockHandled;

packages/block-editor/src/components/inserter/index.js

@@ -46,6 +46,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.
@@ -64,6 +65,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.
 	 *

packages/block-editor/src/components/multi-select-scroll-into-view/index.js

@@ -25,8 +25,6 @@ class MultiSelectScrollIntoView extends Component {
 	/**
 	 * Ensures that if a multi-selection exists, the extent of the selection is
 	 * visible within the nearest scrollable container.
-	 *
-	 * @return {void}
 	 */
 	scrollIntoView() {
 		const { extentClientId } = this.props;

packages/block-editor/src/hooks/align.js

@@ -23,7 +23,7 @@ import { BlockControls, BlockAlignmentToolbar } from '../components';
  *
  * @constant
  * @type {string[]}
-*/
+ */
 const ALL_ALIGNMENTS = [ 'left', 'center', 'right', 'wide', 'full' ];
 
 /**
@@ -33,7 +33,7 @@ const ALL_ALIGNMENTS = [ 'left', 'center', 'right', 'wide', 'full' ];
  *
  * @constant
  * @type {string[]}
-*/
+ */
 const WIDE_ALIGNMENTS = [ 'wide', 'full' ];
 
 /**

packages/block-editor/src/hooks/anchor.js

@@ -56,7 +56,7 @@ export function addAttribute( settings ) {
  * Override the default edit UI to include a new block inspector control for
  * assigning the anchor ID, if block supports anchor.
  *
- * @param {function|Component} BlockEdit Original component.
+ * @param {Function|Component} BlockEdit Original component.
  *
  * @return {string} Wrapped component.
  */

packages/block-editor/src/hooks/custom-class-name.js

@@ -47,7 +47,7 @@ export function addAttribute( settings ) {
  * Override the default edit UI to include a new block inspector control for
  * assigning the custom class name, if block supports custom class name.
  *
- * @param {function|Component} BlockEdit Original component.
+ * @param {Function|Component} BlockEdit Original component.
  *
  * @return {string} Wrapped component.
  */

packages/block-editor/src/store/actions.js

@@ -208,7 +208,7 @@ export function clearSelectedBlock() {
  *
  * @param {boolean} [isSelectionEnabled=true] Whether block selection should
  *                                            be enabled.
-
+ *
  * @return {Object} Action object.
  */
 export function toggleSelection( isSelectionEnabled = true ) {
@@ -227,7 +227,7 @@ export function toggleSelection( isSelectionEnabled = true ) {
  * @param {number}            indexToSelect Index of replacement block to
  *                                          select.
  *
- * @yields {Object} Action object.
+ * @yield {Object} Action object.
  */
 export function* replaceBlocks( clientIds, blocks, indexToSelect ) {
 	clientIds = castArray( clientIds );
@@ -303,7 +303,7 @@ export const moveBlocksUp = createOnMove( 'MOVE_BLOCKS_UP' );
  * @param  {?string} toRootClientId   Root client ID destination.
  * @param  {number}  index            The index to move the block into.
  *
- * @yields {Object} Action object.
+ * @yield {Object} Action object.
  */
 export function* moveBlockToPosition( clientId, fromRootClientId = '', toRootClientId = '', index ) {
 	const templateLock = yield select(

packages/block-editor/src/store/reducer.js

@@ -581,7 +581,7 @@ const withSaveReusableBlock = ( reducer ) => ( state, action ) => {
  * @param {Object} state  Current state.
  * @param {Object} action Dispatched action.
  *
- * @returns {Object} Updated state.
+ * @return {Object} Updated state.
  */
 export const blocks = flow(
 	combineReducers,

packages/block-editor/src/store/selectors.js

@@ -169,7 +169,7 @@ export const __unstableGetBlockWithoutInnerBlocks = createSelector(
  * on each call
  *
  * @param {Object}  state        Editor state.
- * @param {?String} rootClientId Optional root client ID of block list.
+ * @param {?string} rootClientId Optional root client ID of block list.
  *
  * @return {Object[]} Post blocks.
  */
@@ -224,7 +224,7 @@ export const getClientIdsWithDescendants = createSelector(
  * The number returned includes nested blocks.
  *
  * @param {Object}  state     Global application state.
- * @param {?String} blockName Optional block name, if specified only blocks of that type will be counted.
+ * @param {?string} blockName Optional block name, if specified only blocks of that type will be counted.
  *
  * @return {number} Number of blocks in the post, or number of blocks with name equal to blockName.
  */
@@ -1297,6 +1297,7 @@ export const getInserterItems = createSelector(
 
 /**
  * Determines whether there are items to show in the inserter.
+ *
  * @param {Object}  state        Editor state.
  * @param {?string} rootClientId Optional root client ID of block list.
  *