chore: Add jsdoc/require-param-type eslint rule (#142)

* feat: add jsdoc/require-param-type eslint rule

* refactor: convert root0 to props

* refactor: add param type

* refactor: converts enum to JS object

* refactor: update LOGTYPE to string union

* refactor: add param type

* merge : Fix merge resolution mistake.

* fix : Add missing JSDoc param types

* fix : JSDoc param-types for object like formats.

* fix : JSDoc param-types in core-list-item

* fix : format for mentioning Arrays in param-types

* fix : formatting in doc comments

* chore : add changeset

* chore : update changeset to patch instead of minor

* chore: update changelog message

---------

Co-authored-by: Amaan Khan <[email protected]>
Co-authored-by: Dovid Levine <[email protected]>

Author: 3 people

.changeset/wet-geckos-check.md

@@ -0,0 +1,9 @@
+---
+"@snapwp/e2e-tests": patch
+"@snapwp/blocks": patch
+"@snapwp/query": patch
+"@snapwp/core": patch
+"@snapwp/next": patch
+---
+
+chore: Enforce `jsdoc/require-param-type` ESLint rule in repository ruleset.

.eslintrc.cjs

@@ -71,6 +71,7 @@ module.exports = {
 
 		// Turn of JSdoc types and use TypeScript types instead.
 		'jsdoc/no-types': [ 'off' ],
+		'jsdoc/require-param-type': [ 'error' ],
 		'jsdoc/require-returns': [ 'warn' ],
 
 		// Restrict the use of empty functions.

packages/blocks/src/block-manager/index.tsx

@@ -13,7 +13,8 @@ export default class BlockManager {
 
 	/**
 	 * Update block definitions to be used while rendering blocks.
-	 * @param blockDefinitions - rendering implementaion for blocks.
+	 *
+	 * @param {BlockDefinitions} blockDefinitions Rendering implementation for blocks.
 	 */
 	public static addBlockDefinitions(
 		blockDefinitions: BlockDefinitions
@@ -25,8 +26,9 @@ export default class BlockManager {
 	}
 
 	/**
-	 * Function to convert a flat list of blocks to a tree depending on `clientId` and `parentClientId`
-	 * @param blockList - A flat list of blocks.
+	 * Function to convert a flat list of blocks to a tree depending on `clientId` and `parentClientId`.
+	 *
+	 * @param {Array<BlockData>} blockList A flat list of blocks.
 	 *
 	 * @return A tree of blocks.
 	 */
@@ -50,7 +52,8 @@ export default class BlockManager {
 	/**
 	 * Mutates the passed the node by adding a render function to a node of block tree.
 	 * if a node uses default renderer(which uses renderedHtml) prunes its children which does not need to be rendered.
-	 * @param node - A flat list of blocks.
+	 *
+	 * @param {BlockTreeNode} node A flat list of blocks.
 	 */
 	public static attachRendererToTreeNode = ( node: BlockTreeNode ): void => {
 		const customBlockDefinition =
@@ -79,7 +82,8 @@ export default class BlockManager {
 
 	/**
 	 * Pre processes a flat list of blocks for rendering.
-	 * @param blockList - A flat list of blocks.
+	 *
+	 * @param {Array<BlockData>} blockList A flat list of blocks.
 	 *
 	 * @return A tree of blocks with render functions.
 	 */

packages/blocks/src/blocks/core-audio.tsx

@@ -9,9 +9,9 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/audio block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.renderedHtml - The block's rendered HTML.
+ * @param {Object}                         props              The props for the block component.
+ * @param {CoreAudioProps['attributes']}   props.attributes   Block attributes.
+ * @param {CoreAudioProps['renderedHtml']} props.renderedHtml The block's rendered HTML.
  *
  * @return The rendered block.
  */

packages/blocks/src/blocks/core-button.tsx

@@ -9,8 +9,8 @@ import type { ButtonHTMLAttributes, ReactNode } from 'react';
 /**
  * Renders the core/button block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
+ * @param {Object}                        props            The props for the block component.
+ * @param {CoreButtonProps['attributes']} props.attributes Block attributes.
  *
  * @return The rendered block.
  */

packages/blocks/src/blocks/core-buttons.tsx

@@ -8,9 +8,9 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/buttons block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.children - The block's children.
+ * @param {Object}                         props            The props for the block component.
+ * @param {CoreButtonsProps['attributes']} props.attributes Block attributes.
+ * @param {ReactNode}                      props.children   The block's children.
  *
  * @return The rendered block.
  */

packages/blocks/src/blocks/core-code.tsx

@@ -6,8 +6,8 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/code block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
+ * @param {Object}                      props            The props for the block component.
+ * @param {CoreCodeProps['attributes']} props.attributes Block attributes.
  *
  * @return The rendered block.
  */

packages/blocks/src/blocks/core-column.tsx

@@ -8,9 +8,9 @@ import type { CSSProperties, ReactNode } from 'react';
 /**
  * Renders the core/column block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.children - The block's children.
+ * @param {Object}                        props            The props for the block component.
+ * @param {CoreColumnProps['attributes']} props.attributes Block attributes.
+ * @param {ReactNode}                     props.children   The block's children.
  *
  * @return The rendered block.
  */

packages/blocks/src/blocks/core-columns.tsx

@@ -8,9 +8,9 @@ import type { ReactNode } from 'react';
 /**
  * Renders the core/columns block.
  *
- * @param props - The props for the block component.
- * @param props.attributes - Block attributes.
- * @param props.children - The block's children.
+ * @param {Object}                         props            The props for the block component.
+ * @param {CoreColumnsProps['attributes']} props.attributes Block attributes.
+ * @param {ReactNode}                      props.children   The block's children.
  *
  * @return The rendered block.
  */

packages/blocks/src/blocks/core-cover.tsx

@@ -22,7 +22,7 @@ const DEFAULT_FOCAL_POINT = { x: 0.5, y: 0.5 };
  *
  * @see https://github.com/WordPress/gutenberg/blob/887243c1cb2b3280934fbff05d4af8e46a3feddc/packages/block-library/src/cover/shared.js#L27
  *
- * @param focalPoint - The focal point coordinates object containing x and y values.
+ * @param {FocalPoint} focalPoint The focal point coordinates object containing x and y values.
  *
  * @return CSS position string or undefined if no focal point
  */
@@ -39,12 +39,13 @@ const mediaPosition = (
 
 /**
  * Renders the core/cover block.
- * @param root0 - The component props object
- * @param root0.attributes - Block attributes including styling and media settings
- * @param root0.children - Child elements to render inside the cover
- * @param root0.renderedHtml - Pre-rendered HTML string for class extraction
- * @param root0.connectedMediaItem - The connected media item object
- * @param root0.mediaDetails - The media details object
+ *
+ * @param {Object}                               props                    The component props object
+ * @param {CoreCoverProps['attributes']}         props.attributes         Block attributes including styling and media settings
+ * @param {ReactNode}                            props.children           Child elements to render inside the cover
+ * @param {CoreCoverProps['renderedHtml']}       props.renderedHtml       Pre-rendered HTML string for class extraction
+ * @param {CoreCoverProps['connectedMediaItem']} props.connectedMediaItem The connected media item object
+ * @param {CoreCoverProps['mediaDetails']}       props.mediaDetails       The media details object
  *
  * @return The rendered cover block or null if using featured image
  */