From 2721092f3a77a8ffd6a4f2a272aa28dc2424d8b5 Mon Sep 17 00:00:00 2001
From: Anuj-Rathore24 <anujsingh2409@gmail.com>
Date: Thu, 23 Jan 2025 19:29:02 +0530
Subject: [PATCH 1/2] Feat: Adds JSDoc for query block.

---
 .../src/query-pagination-next/edit.js         | 12 ++++++++
 .../src/query-pagination-numbers/edit.js      | 16 ++++++++++
 .../src/query-pagination-previous/edit.js     | 13 +++++++++
 .../src/query-pagination/edit.js              | 11 +++++++
 .../query/edit/enhanced-pagination-modal.js   | 11 +++++++
 .../block-library/src/query/edit/index.js     |  9 ++++++
 .../src/query/edit/pattern-selection.js       | 29 +++++++++++++++++++
 .../src/query/edit/query-content.js           | 12 ++++++++
 .../src/query/edit/query-placeholder.js       | 20 +++++++++++++
 .../src/query/edit/query-toolbar.js           |  8 +++++
 10 files changed, 141 insertions(+)

diff --git a/packages/block-library/src/query-pagination-next/edit.js b/packages/block-library/src/query-pagination-next/edit.js
index 2bd38277a4b6c0..0d3994dab0a4f1 100644
--- a/packages/block-library/src/query-pagination-next/edit.js
+++ b/packages/block-library/src/query-pagination-next/edit.js
@@ -10,6 +10,18 @@ const arrowMap = {
 	chevron: '»',
 };
 
+/*
+ * QueryPaginationNextEdit component provides the block editor interface for editing the "Next" pagination link.
+ *
+ * @param {Object} props                               Component props.
+ * @param {Object} props.attributes                    Block attributes.
+ * @param {string} props.attributes.label              The label text for the "Next" pagination link.
+ * @param {Function} props.setAttributes               Function to update block attributes.
+ * @param {Object} props.context                       Contextual data passed to the block.
+ * @param {string} props.context.paginationArrow       Type of arrow to display for pagination (e.g., 'none', 'arrow').
+ * @param {boolean} props.context.showLabel            Determines whether the label text is shown.
+ * @return {JSX.Element}                               The rendered block editor interface for the "Next" pagination link.
+ */
 export default function QueryPaginationNextEdit( {
 	attributes: { label },
 	setAttributes,
diff --git a/packages/block-library/src/query-pagination-numbers/edit.js b/packages/block-library/src/query-pagination-numbers/edit.js
index a03ed8419bb086..a0d4a50701d436 100644
--- a/packages/block-library/src/query-pagination-numbers/edit.js
+++ b/packages/block-library/src/query-pagination-numbers/edit.js
@@ -20,6 +20,12 @@ const createPaginationItem = ( content, Tag = 'a', extraClass = '' ) => (
 	</Tag>
 );
 
+/*
+ * Generates a preview of pagination numbers based on the specified mid-size value.
+ *
+ * @param {number} midSize The number of links to display before and after the current page.
+ * @return {JSX.Element} A JSX fragment containing the pagination items.
+ */
 const previewPaginationNumbers = ( midSize ) => {
 	const paginationItems = [];
 
@@ -47,6 +53,16 @@ const previewPaginationNumbers = ( midSize ) => {
 	return <>{ paginationItems }</>;
 };
 
+/*
+ * QueryPaginationNumbersEdit component provides the block editor interface
+ * for editing the pagination numbers display.
+ *
+ * @param {Object} props                    		Component props.
+ * @param {Object} props.attributes         		Block attributes.
+ * @param {number} props.attributes.midSize 		The number of links before and after the current page.
+ * @param {Function} props.setAttributes    		Function to update block attributes.
+ * @return {JSX.Element} 							The rendered block editor interface for pagination numbers.
+ */
 export default function QueryPaginationNumbersEdit( {
 	attributes,
 	setAttributes,
diff --git a/packages/block-library/src/query-pagination-previous/edit.js b/packages/block-library/src/query-pagination-previous/edit.js
index b32f15052f2e64..c28e597afe624d 100644
--- a/packages/block-library/src/query-pagination-previous/edit.js
+++ b/packages/block-library/src/query-pagination-previous/edit.js
@@ -10,6 +10,19 @@ const arrowMap = {
 	chevron: '«',
 };
 
+/*
+ * QueryPaginationPreviousEdit component provides the block editor interface
+ * for editing the "Previous Page" pagination link.
+ *
+ * @param {Object} props                        	Component props.
+ * @param {Object} props.attributes             	Block attributes.
+ * @param {string} props.attributes.label       	The label displayed for the "Previous Page" link.
+ * @param {Function} props.setAttributes        	Function to update block attributes.
+ * @param {Object} props.context                	Block context.
+ * @param {string} props.context.paginationArrow 	The type of arrow to display (e.g., left arrow).
+ * @param {boolean} props.context.showLabel     	Whether to display the label for the pagination link.
+ * @return {JSX.Element} 							The rendered block editor interface for the "Previous Page" link.
+ */
 export default function QueryPaginationPreviousEdit( {
 	attributes: { label },
 	setAttributes,
diff --git a/packages/block-library/src/query-pagination/edit.js b/packages/block-library/src/query-pagination/edit.js
index 8ca0705058be28..075348630865f8 100644
--- a/packages/block-library/src/query-pagination/edit.js
+++ b/packages/block-library/src/query-pagination/edit.js
@@ -28,6 +28,17 @@ const TEMPLATE = [
 	[ 'core/query-pagination-next' ],
 ];
 
+/*
+ * QueryPaginationEdit component provides the block editor interface for editing pagination settings.
+ *
+ * @param {Object} props                              	Component props.
+ * @param {Object} props.attributes                  	Block attributes.
+ * @param {string} props.attributes.paginationArrow  	Defines the type of arrow to display for pagination (e.g., 'none', 'arrow').
+ * @param {boolean} props.attributes.showLabel       	Determines whether label text is shown with pagination.
+ * @param {Function} props.setAttributes             	Function to update block attributes.
+ * @param {string} props.clientId                    	The client ID of the block.
+ * @return {JSX.Element}                             	The rendered block editor interface.
+ */
 export default function QueryPaginationEdit( {
 	attributes: { paginationArrow, showLabel },
 	setAttributes,
diff --git a/packages/block-library/src/query/edit/enhanced-pagination-modal.js b/packages/block-library/src/query/edit/enhanced-pagination-modal.js
index 332cc337bb0f67..872b15f4093f78 100644
--- a/packages/block-library/src/query/edit/enhanced-pagination-modal.js
+++ b/packages/block-library/src/query/edit/enhanced-pagination-modal.js
@@ -17,6 +17,17 @@ import { useUnsupportedBlocks } from '../utils';
 const modalDescriptionId =
 	'wp-block-query-enhanced-pagination-modal__description';
 
+/*
+ * EnhancedPaginationModal - Renders a modal for handling enhanced pagination settings in the Query block.
+ *
+ * @param {Object} props                          			The component properties.
+ * @param {string} props.clientId                 			The client ID of the Query block.
+ * @param {Object} props.attributes               			The attributes of the Query block.
+ * @param {boolean} props.attributes.enhancedPagination 	Whether enhanced pagination is enabled.
+ * @param {Function} props.setAttributes          			Function to update block attributes.
+ *
+ * @returns {JSX.Element|null} 								The rendered modal if conditions are met; otherwise, null.
+ */
 export default function EnhancedPaginationModal( {
 	clientId,
 	attributes: { enhancedPagination },
diff --git a/packages/block-library/src/query/edit/index.js b/packages/block-library/src/query/edit/index.js
index 60fc2ebd6170b3..9d78db322ce546 100644
--- a/packages/block-library/src/query/edit/index.js
+++ b/packages/block-library/src/query/edit/index.js
@@ -12,6 +12,15 @@ import QueryContent from './query-content';
 import QueryPlaceholder from './query-placeholder';
 import { PatternSelectionModal } from './pattern-selection';
 
+/*
+ * QueryEdit - The edit component for the Query block in the WordPress block editor.
+ *
+ * @param {Object} props                    The component properties.
+ * @param {string} props.clientId           The unique client ID of the Query block.
+ * @param {Object} props.attributes         The attributes of the Query block.
+ *
+ * @returns {JSX.Element} 					The rendered Query block edit interface.
+ */
 const QueryEdit = ( props ) => {
 	const { clientId, attributes } = props;
 	const [ isPatternSelectionModalOpen, setIsPatternSelectionModalOpen ] =
diff --git a/packages/block-library/src/query/edit/pattern-selection.js b/packages/block-library/src/query/edit/pattern-selection.js
index 0c5d95d15206f2..e8f94f33da9a0f 100644
--- a/packages/block-library/src/query/edit/pattern-selection.js
+++ b/packages/block-library/src/query/edit/pattern-selection.js
@@ -21,6 +21,16 @@ import {
 } from '../utils';
 import { searchPatterns } from '../../utils/search-patterns';
 
+/*
+ * Renders a modal for selecting a block pattern.
+ *
+ * @param {Object} props                               		Component properties.
+ * @param {string} props.clientId                      		The client ID of the block.
+ * @param {Object} props.attributes                    		The attributes of the block.
+ * @param {Function} props.setIsPatternSelectionModalOpen 	Function to toggle the modal state.
+ *
+ * @returns {JSX.Element} 									The rendered Pattern Selection Modal.
+ */
 export function PatternSelectionModal( {
 	clientId,
 	attributes,
@@ -38,6 +48,14 @@ export function PatternSelectionModal( {
 	);
 }
 
+/*
+ * Hook to retrieve block patterns based on the block's client ID and attributes.
+ *
+ * @param {string} clientId     The client ID of the block.
+ * @param {Object} attributes   The attributes of the block.
+ *
+ * @returns {Array} 			An array of block patterns.
+ */
 export function useBlockPatterns( clientId, attributes ) {
 	const blockNameForPatterns = useBlockNameForPatterns(
 		clientId,
@@ -46,6 +64,17 @@ export function useBlockPatterns( clientId, attributes ) {
 	return usePatterns( clientId, blockNameForPatterns );
 }
 
+/*
+ * Component for displaying and selecting block patterns.
+ *
+ * @param {Object} props                          	Component properties.
+ * @param {string} props.clientId                 	The client ID of the block.
+ * @param {Object} props.attributes               	The attributes of the block.
+ * @param {boolean} [props.showTitlesAsTooltip]   	Whether to show titles as tooltips (default: false).
+ * @param {boolean} [props.showSearch]            	Whether to show the search bar (default: true).
+ *
+ * @returns {JSX.Element} 							The rendered pattern selection interface.
+ */
 export default function PatternSelection( {
 	clientId,
 	attributes,
diff --git a/packages/block-library/src/query/edit/query-content.js b/packages/block-library/src/query/edit/query-content.js
index 459ce2af018c2a..92a9683ad18e28 100644
--- a/packages/block-library/src/query/edit/query-content.js
+++ b/packages/block-library/src/query/edit/query-content.js
@@ -28,6 +28,18 @@ import { htmlElementMessages } from '../../utils/messages';
 const DEFAULTS_POSTS_PER_PAGE = 3;
 
 const TEMPLATE = [ [ 'core/post-template' ] ];
+
+/*
+ * QueryContent component for managing and rendering query-related block content.
+ *
+ * @param {Object}   props 							Component props.
+ * @param {Object}   props.attributes 				Block attributes.
+ * @param {Function} props.setAttributes 			Function to update block attributes.
+ * @param {string}   props.clientId 				The client ID of the block.
+ * @param {Object}   props.context 					Context data for the block.
+ * @param {string}   props.name 					The block name.
+ * @return {JSX.Element} 							The rendered QueryContent component.
+ */
 export default function QueryContent( {
 	attributes,
 	setAttributes,
diff --git a/packages/block-library/src/query/edit/query-placeholder.js b/packages/block-library/src/query/edit/query-placeholder.js
index c3a01a0447f55e..375050183c160b 100644
--- a/packages/block-library/src/query/edit/query-placeholder.js
+++ b/packages/block-library/src/query/edit/query-placeholder.js
@@ -21,6 +21,16 @@ import { __ } from '@wordpress/i18n';
 import { useScopedBlockVariations } from '../utils';
 import { useBlockPatterns } from './pattern-selection';
 
+/*
+ * QueryPlaceholder component for rendering a placeholder with options to choose a pattern or start blank.
+ *
+ * @param {Object}   props 								Component props.
+ * @param {Object}   props.attributes 					Block attributes.
+ * @param {string}   props.clientId 					The client ID of the block.
+ * @param {string}   props.name 						The block name.
+ * @param {Function} props.openPatternSelectionModal 	Function to open the pattern selection modal.
+ * @return {JSX.Element} 								The rendered QueryPlaceholder component.
+ */
 export default function QueryPlaceholder( {
 	attributes,
 	clientId,
@@ -92,6 +102,16 @@ export default function QueryPlaceholder( {
 	);
 }
 
+/*
+ * QueryVariationPicker component for selecting a block variation.
+ *
+ * @param {Object}   props 						Component props.
+ * @param {string}   props.clientId 			The client ID of the block.
+ * @param {Object}   props.attributes 			Block attributes.
+ * @param {string}   props.icon 				Icon for the variation picker.
+ * @param {string}   props.label 				Label for the variation picker.
+ * @return {JSX.Element} 						The rendered QueryVariationPicker component.
+ */
 function QueryVariationPicker( { clientId, attributes, icon, label } ) {
 	const scopeVariations = useScopedBlockVariations( attributes );
 	const { replaceInnerBlocks } = useDispatch( blockEditorStore );
diff --git a/packages/block-library/src/query/edit/query-toolbar.js b/packages/block-library/src/query/edit/query-toolbar.js
index 25e087ebe1559c..66cbd3a97b6bb4 100644
--- a/packages/block-library/src/query/edit/query-toolbar.js
+++ b/packages/block-library/src/query/edit/query-toolbar.js
@@ -14,6 +14,14 @@ import { __ } from '@wordpress/i18n';
  */
 import PatternSelection, { useBlockPatterns } from './pattern-selection';
 
+/*
+ * QueryToolbar component renders a toolbar for selecting and changing design patterns.
+ *
+ * @param {Object} props                     Component props.
+ * @param {string} props.clientId            The client ID of the block.
+ * @param {Object} props.attributes          The block attributes.
+ * @return {JSX.Element|null}                The rendered toolbar or null if no patterns are available.
+ */
 export default function QueryToolbar( { clientId, attributes } ) {
 	const hasPatterns = useBlockPatterns( clientId, attributes ).length;
 	if ( ! hasPatterns ) {

From afbcd71ef24c2096bf695f44a290e3526d1c8f8f Mon Sep 17 00:00:00 2001
From: Anuj-Rathore24 <anujsingh2409@gmail.com>
Date: Fri, 24 Jan 2025 19:21:40 +0530
Subject: [PATCH 2/2] Feat: Adds JSdoc for query block.

---
 packages/block-library/src/query-title/edit.js  | 15 +++++++++++++++
 packages/block-library/src/query-total/edit.js  | 10 ++++++++++
 .../edit/inspector-controls/author-control.js   |  8 ++++++++
 .../enhanced-pagination-control.js              |  9 +++++++++
 .../edit/inspector-controls/format-controls.js  | 17 ++++++++++++++++-
 .../edit/inspector-controls/offset-controls.js  |  8 ++++++++
 6 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/packages/block-library/src/query-title/edit.js b/packages/block-library/src/query-title/edit.js
index 0da6da47ef6147..e73a29faa22e08 100644
--- a/packages/block-library/src/query-title/edit.js
+++ b/packages/block-library/src/query-title/edit.js
@@ -29,6 +29,21 @@ import { useToolsPanelDropdownMenuProps } from '../utils/hooks';
 
 const SUPPORTED_TYPES = [ 'archive', 'search' ];
 
+/*
+ * QueryTitleEdit component provides the block editor interface for rendering and editing the title
+ * of a query-based block, such as archive titles or search result titles.
+ *
+ * @param {Object} props                        		Component props.
+ * @param {Object} props.attributes             		Block attributes.
+ * @param {string} props.attributes.type        		The type of query (e.g., 'archive' or 'search').
+ * @param {number} props.attributes.level       		The heading level for the title (e.g., 1 for `<h1>`).
+ * @param {Array}  props.attributes.levelOptions 		Available heading level options.
+ * @param {string} props.attributes.textAlign   		Text alignment for the title (e.g., 'left', 'center').
+ * @param {boolean} props.attributes.showPrefix 		Whether to show the archive type prefix (e.g., 'Category:').
+ * @param {boolean} props.attributes.showSearchTerm 	Whether to show the search term in the title.
+ * @param {Function} props.setAttributes        		Function to update block attributes.
+ * @return {JSX.Element} 								The rendered block editor interface for the query title.
+ */
 export default function QueryTitleEdit( {
 	attributes: {
 		type,
diff --git a/packages/block-library/src/query-total/edit.js b/packages/block-library/src/query-total/edit.js
index d91a1990715727..e2d22703ffad9d 100644
--- a/packages/block-library/src/query-total/edit.js
+++ b/packages/block-library/src/query-total/edit.js
@@ -10,6 +10,16 @@ import { __ } from '@wordpress/i18n';
  */
 import { resultsFound, displayingResults } from './icons';
 
+/*
+ * QueryTotalEdit component provides the block editor interface for rendering and editing
+ * the total query results or a range display for query results.
+ *
+ * @param {Object} props                        	Component props.
+ * @param {Object} props.attributes             	Block attributes.
+ * @param {string} props.attributes.displayType 	The selected display type ('total-results' or 'range-display').
+ * @param {Function} props.setAttributes        	Function to update block attributes.
+ * @return {JSX.Element} 							The rendered block editor interface for the query total display.
+ */
 export default function QueryTotalEdit( { attributes, setAttributes } ) {
 	const { displayType } = attributes;
 
diff --git a/packages/block-library/src/query/edit/inspector-controls/author-control.js b/packages/block-library/src/query/edit/inspector-controls/author-control.js
index 4379dfe3e46cb6..94d1d7755d8511 100644
--- a/packages/block-library/src/query/edit/inspector-controls/author-control.js
+++ b/packages/block-library/src/query/edit/inspector-controls/author-control.js
@@ -18,6 +18,14 @@ const AUTHORS_QUERY = {
 	context: 'view',
 };
 
+/*
+ * AuthorControl component for managing and selecting authors.
+ *
+ * @param {Object} props         		Component props.
+ * @param {string} props.value   		Comma-separated string of selected author IDs.
+ * @param {Function} props.onChange 	Callback function to handle changes in selected authors.
+ * @return {JSX.Element|null} 			The rendered AuthorControl component or null if no authors are available.
+ */
 function AuthorControl( { value, onChange } ) {
 	const authorsList = useSelect( ( select ) => {
 		const { getUsers } = select( coreStore );
diff --git a/packages/block-library/src/query/edit/inspector-controls/enhanced-pagination-control.js b/packages/block-library/src/query/edit/inspector-controls/enhanced-pagination-control.js
index 4d0b1a9fd9da37..7bd7ac7825ae56 100644
--- a/packages/block-library/src/query/edit/inspector-controls/enhanced-pagination-control.js
+++ b/packages/block-library/src/query/edit/inspector-controls/enhanced-pagination-control.js
@@ -9,6 +9,15 @@ import { __ } from '@wordpress/i18n';
  */
 import { useUnsupportedBlocks } from '../../utils';
 
+/*
+ * EnhancedPaginationControl component for managing the pagination behavior.
+ *
+ * @param {Object} props                          	Component props.
+ * @param {boolean} props.enhancedPagination      	Indicates whether enhanced pagination is enabled.
+ * @param {Function} props.setAttributes          	Callback function to update block attributes.
+ * @param {string} props.clientId                 	The client ID of the block.
+ * @return {JSX.Element} 							The rendered EnhancedPaginationControl component.
+ */
 export default function EnhancedPaginationControl( {
 	enhancedPagination,
 	setAttributes,
diff --git a/packages/block-library/src/query/edit/inspector-controls/format-controls.js b/packages/block-library/src/query/edit/inspector-controls/format-controls.js
index 15c95f3bbba2e2..bff8bb8b5f771c 100644
--- a/packages/block-library/src/query/edit/inspector-controls/format-controls.js
+++ b/packages/block-library/src/query/edit/inspector-controls/format-controls.js
@@ -32,7 +32,13 @@ const POST_FORMATS = [
 	return 0;
 } );
 
-// A helper function to convert translatable post format names into their static values.
+/*
+ * A helper function to convert translatable post format names into their static values.
+ *
+ * @param {string[]} names   	Array of format names (translatable labels).
+ * @param {Object[]} formats 	Array of format objects with `label` and `value` properties.
+ * @return {string[]} 			Array of format values corresponding to the provided names.
+ */
 function formatNamesToValues( names, formats ) {
 	return names
 		.map( ( name ) => {
@@ -44,6 +50,15 @@ function formatNamesToValues( names, formats ) {
 		.filter( Boolean );
 }
 
+/*
+ * FormatControls component for managing and selecting post formats.
+ *
+ * @param {Object} props                    		Component props.
+ * @param {Function} props.onChange         		Callback function to handle changes in selected formats.
+ * @param {Object} props.query              		Query object containing format information.
+ * @param {string|string[]} props.query.format 		The current selected format(s), either as a string or an array.
+ * @return {JSX.Element} 							The rendered FormatControls component.
+ */
 export default function FormatControls( { onChange, query: { format } } ) {
 	// 'format' is expected to be an array. If it is not an array, for example
 	// if a user has manually entered an invalid value in the block markup,
diff --git a/packages/block-library/src/query/edit/inspector-controls/offset-controls.js b/packages/block-library/src/query/edit/inspector-controls/offset-controls.js
index ff755c95f8b0a9..c0436c12053565 100644
--- a/packages/block-library/src/query/edit/inspector-controls/offset-controls.js
+++ b/packages/block-library/src/query/edit/inspector-controls/offset-controls.js
@@ -7,6 +7,14 @@ import { __ } from '@wordpress/i18n';
 const MIN_OFFSET = 0;
 const MAX_OFFSET = 100;
 
+/*
+ * OffsetControl component for adjusting the offset value.
+ *
+ * @param {Object} props            	Component props.
+ * @param {number} [props.offset=0] 	Current offset value. Defaults to 0 if not provided.
+ * @param {Function} props.onChange 	Callback function to handle changes to the offset value.
+ * @return {JSX.Element} 				The rendered OffsetControl component.
+ */
 export const OffsetControl = ( { offset = 0, onChange } ) => {
 	return (
 		<NumberControl