From b258918417d6827434d2df36711f3249d91e7174 Mon Sep 17 00:00:00 2001 From: dhruvikpatel18 Date: Fri, 24 Jan 2025 13:16:30 +0530 Subject: [PATCH 1/4] feat: Adds Jsdoc comment for avatar block. --- packages/block-library/src/avatar/edit.js | 31 +++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/packages/block-library/src/avatar/edit.js b/packages/block-library/src/avatar/edit.js index 8309bc5e878a0e..6d304135ba58b3 100644 --- a/packages/block-library/src/avatar/edit.js +++ b/packages/block-library/src/avatar/edit.js @@ -26,6 +26,16 @@ import { addQueryArgs, removeQueryArgs } from '@wordpress/url'; import { useUserAvatar, useCommentAvatar } from './hooks'; import UserControl from './user-control'; +/* + * Avatar block inspector controls. + * + * @param {Object} props Component props. + * @param {Function} props.setAttributes Function to set attributes. + * @param {Object} props.avatar Avatar data. + * @param {Object} props.attributes Block attributes. + * @param {boolean} props.selectUser Whether to show user selection control. + * @return {JSX.Element} InspectorControls component. + */ const AvatarInspectorControls = ( { setAttributes, avatar, @@ -82,6 +92,17 @@ const AvatarInspectorControls = ( { ); +/* + * Resizable avatar component. + * + * @param {Object} props Component props. + * @param {Function} props.setAttributes Function to set attributes. + * @param {Object} props.attributes Block attributes. + * @param {Object} props.avatar Avatar data. + * @param {Object} props.blockProps Block properties. + * @param {boolean} props.isSelected Whether the block is selected. + * @return {JSX.Element} Resizable avatar component. + */ const ResizableAvatar = ( { setAttributes, attributes, @@ -220,6 +241,16 @@ const UserEdit = ( { attributes, context, setAttributes, isSelected } ) => { ); }; +/* + * Edit component for the Avatar block. + * + * @param {Object} props Component props. + * @param {Object} props.attributes Block attributes. + * @param {Object} props.context Block context. + * @param {Function} props.setAttributes Function to update block attributes. + * @param {boolean} props.isSelected Whether the block is currently selected. + * @return {JSX.Element} Rendered Avatar block edit component. + */ export default function Edit( props ) { // Don't show the Comment Edit controls if we have a comment ID set, or if we're in the Site Editor (where it is `null`). if ( props?.context?.commentId || props?.context?.commentId === null ) { From 1e922a57edbfb16d71a2a23ace7a391d0217cf0c Mon Sep 17 00:00:00 2001 From: dhruvikpatel18 Date: Thu, 13 Aug 2026 12:18:11 +0530 Subject: [PATCH 2/4] Refactor: Update JSDoc comments for Avatar block components --- packages/block-library/src/avatar/edit.js | 97 +++++++++++++++++------ 1 file changed, 72 insertions(+), 25 deletions(-) diff --git a/packages/block-library/src/avatar/edit.js b/packages/block-library/src/avatar/edit.js index c43f801998d69f..4c10036a2e7b7e 100644 --- a/packages/block-library/src/avatar/edit.js +++ b/packages/block-library/src/avatar/edit.js @@ -17,15 +17,16 @@ import { useToolsPanelDropdownMenuProps } from '../utils/hooks'; import { useCommentAvatar, useUserAvatar } from './hooks'; import UserControl from './user-control'; -/* - * Avatar block inspector controls. +/** + * Renders the inspector controls for the `core/avatar` block. * - * @param {Object} props Component props. - * @param {Function} props.setAttributes Function to set attributes. - * @param {Object} props.avatar Avatar data. - * @param {Object} props.attributes Block attributes. - * @param {boolean} props.selectUser Whether to show user selection control. - * @return {JSX.Element} InspectorControls component. + * @param {Object} props React props. + * @param {Function} props.setAttributes Callback for updating block attributes. + * @param {Object} props.avatar Avatar data returned by `useCommentAvatar` or `useUserAvatar`, with the `minSize` and `maxSize` bounds of the size control. + * @param {Object} props.attributes Block attributes: `size`, `isLink`, `linkTarget` and `userId`. + * @param {boolean} props.selectUser Whether to render the user selection control. + * + * @return {React.JSX.Element} React element. */ const AvatarInspectorControls = ( { setAttributes, @@ -125,6 +126,17 @@ const AvatarInspectorControls = ( { ); }; +/** + * Wraps the avatar image in a placeholder link when the block links to the user + * profile. The link is inert in the editor: it points at a fragment and its + * click handler prevents navigation. + * + * @param {Object} props React props. + * @param {React.ReactNode} props.children Avatar image to wrap. + * @param {boolean} props.isLink Whether to wrap the children in a link. + * + * @return {React.JSX.Element} React element. + */ const AvatarLinkWrapper = ( { children, isLink } ) => isLink ? ( children ); -/* - * Resizable avatar component. +/** + * Renders the avatar image inside a `ResizableBox` so its size can be adjusted + * by dragging. Resizing keeps the aspect ratio and updates the `size` attribute. * - * @param {Object} props Component props. - * @param {Function} props.setAttributes Function to set attributes. - * @param {Object} props.attributes Block attributes. - * @param {Object} props.avatar Avatar data. - * @param {Object} props.blockProps Block properties. - * @param {boolean} props.isSelected Whether the block is selected. - * @return {JSX.Element} Resizable avatar component. + * @param {Object} props React props. + * @param {Function} props.setAttributes Callback for updating block attributes. + * @param {Object} props.attributes Block attributes: `size` and `isLink`, plus the border support values read by `useBorderProps`. + * @param {Object} props.avatar Avatar data returned by `useCommentAvatar` or `useUserAvatar`, with the image `src` and `alt` and the `minSize` and `maxSize` resize bounds. + * @param {Object} props.blockProps Props returned by `useBlockProps`, applied to the wrapper element. + * @param {boolean} props.isSelected Whether the block is selected. Resize handles are only shown when it is. + * + * @return {React.JSX.Element} React element. */ const ResizableAvatar = ( { setAttributes, @@ -208,6 +222,20 @@ const ResizableAvatar = ( { ); }; + +/** + * Renders the block for a comment author, resolving the avatar from the + * `commentId` context. The user selection control is not offered here because + * the author is determined by the comment. + * + * @param {Object} props React props. + * @param {Object} props.attributes Block attributes. + * @param {Object} props.context Inherited context, from which the comment ID is read. + * @param {Function} props.setAttributes Callback for updating block attributes. + * @param {boolean} props.isSelected Whether the block is selected. + * + * @return {React.JSX.Element} React element. + */ const CommentEdit = ( { attributes, context, setAttributes, isSelected } ) => { const { commentId } = context; const blockProps = useBlockProps(); @@ -231,6 +259,19 @@ const CommentEdit = ( { attributes, context, setAttributes, isSelected } ) => { ); }; +/** + * Renders the block for a user, resolving the avatar from the `userId` + * attribute when set, and otherwise from the author of the post identified by + * the `postType` and `postId` context. + * + * @param {Object} props React props. + * @param {Object} props.attributes Block attributes, from which the `userId` is read. + * @param {Object} props.context Inherited context, from which the post type and post ID are read. + * @param {Function} props.setAttributes Callback for updating block attributes. + * @param {boolean} props.isSelected Whether the block is selected. + * + * @return {React.JSX.Element} React element. + */ const UserEdit = ( { attributes, context, setAttributes, isSelected } ) => { const { postId, postType } = context; const avatar = useUserAvatar( { @@ -259,15 +300,21 @@ const UserEdit = ( { attributes, context, setAttributes, isSelected } ) => { ); }; -/* - * Edit component for the Avatar block. +/** + * Renders the `core/avatar` block on the editor. All props are forwarded to + * either `CommentEdit` or `UserEdit`, depending on whether the block is used + * inside a comment. + * + * @param {Object} props React props. + * @param {Object} props.attributes Block attributes. + * @param {Object} props.context Inherited context. + * @param {number} [props.context.commentId] The comment ID. Present, possibly as `null` in the Site Editor, when the block is used inside a comment. + * @param {string} [props.context.postType] The post type of the current post. + * @param {number} [props.context.postId] The ID of the current post. + * @param {Function} props.setAttributes Callback for updating block attributes. + * @param {boolean} props.isSelected Whether the block is selected. * - * @param {Object} props Component props. - * @param {Object} props.attributes Block attributes. - * @param {Object} props.context Block context. - * @param {Function} props.setAttributes Function to update block attributes. - * @param {boolean} props.isSelected Whether the block is currently selected. - * @return {JSX.Element} Rendered Avatar block edit component. + * @return {React.JSX.Element} React element. */ export default function Edit( props ) { // Don't show the Comment Edit controls if we have a comment ID set, or if we're in the Site Editor (where it is `null`). From 0d6157ce8f3d74d57f76c7c2a54a5f3ac54ae470 Mon Sep 17 00:00:00 2001 From: dhruvikpatel18 Date: Thu, 13 Aug 2026 17:54:52 +0530 Subject: [PATCH 3/4] Refactor: Improve JSDoc comments for UserEdit component in Avatar block --- packages/block-library/src/avatar/edit.js | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/block-library/src/avatar/edit.js b/packages/block-library/src/avatar/edit.js index 4c10036a2e7b7e..588e42f8255a4f 100644 --- a/packages/block-library/src/avatar/edit.js +++ b/packages/block-library/src/avatar/edit.js @@ -305,14 +305,14 @@ const UserEdit = ( { attributes, context, setAttributes, isSelected } ) => { * either `CommentEdit` or `UserEdit`, depending on whether the block is used * inside a comment. * - * @param {Object} props React props. - * @param {Object} props.attributes Block attributes. - * @param {Object} props.context Inherited context. - * @param {number} [props.context.commentId] The comment ID. Present, possibly as `null` in the Site Editor, when the block is used inside a comment. - * @param {string} [props.context.postType] The post type of the current post. - * @param {number} [props.context.postId] The ID of the current post. - * @param {Function} props.setAttributes Callback for updating block attributes. - * @param {boolean} props.isSelected Whether the block is selected. + * @param {Object} props React props. + * @param {Object} props.attributes Block attributes. + * @param {Object} props.context Inherited context. + * @param {number|null} [props.context.commentId] The comment ID when the block is used inside a comment. `null` in the Site Editor, where no comment is resolved but the comment variant is still rendered. + * @param {string} [props.context.postType] The post type of the current post. + * @param {number} [props.context.postId] The ID of the current post. + * @param {Function} props.setAttributes Callback for updating block attributes. + * @param {boolean} props.isSelected Whether the block is selected. * * @return {React.JSX.Element} React element. */ From 359ed22146d618ed36b20b3483ba1a8eb7ca83ab Mon Sep 17 00:00:00 2001 From: dhruvikpatel18 Date: Thu, 13 Aug 2026 18:01:49 +0530 Subject: [PATCH 4/4] Refactor: Update return type in JSDoc for AvatarLinkWrapper component --- packages/block-library/src/avatar/edit.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/block-library/src/avatar/edit.js b/packages/block-library/src/avatar/edit.js index 588e42f8255a4f..b5ea80858c0ded 100644 --- a/packages/block-library/src/avatar/edit.js +++ b/packages/block-library/src/avatar/edit.js @@ -135,7 +135,7 @@ const AvatarInspectorControls = ( { * @param {React.ReactNode} props.children Avatar image to wrap. * @param {boolean} props.isLink Whether to wrap the children in a link. * - * @return {React.JSX.Element} React element. + * @return {React.ReactNode} The children, wrapped in a link when `isLink` is true. */ const AvatarLinkWrapper = ( { children, isLink } ) => isLink ? (