Adds JSdoc for avatar block's edit.js

packages/block-library/src/avatar/edit.js

@@ -17,6 +17,17 @@ import { useToolsPanelDropdownMenuProps } from '../utils/hooks';
 import { useCommentAvatar, useUserAvatar } from './hooks';
 import UserControl from './user-control';
 
+/**
+ * Renders the inspector controls for the `core/avatar` block.
+ *
+ * @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,
 	avatar,
@@ -115,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.ReactNode} The children, wrapped in a link when `isLink` is true.
+ */
 const AvatarLinkWrapper = ( { children, isLink } ) =>
 	isLink ? (
 		<a
@@ -128,6 +150,19 @@ const AvatarLinkWrapper = ( { children, isLink } ) =>
 		children
 	);
 
+/**
+ * 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               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,
 	attributes,
@@ -187,6 +222,20 @@ const ResizableAvatar = ( {
 		</div>
 	);
 };
+
+/**
+ * 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();
@@ -210,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( {
@@ -238,6 +300,22 @@ const UserEdit = ( { attributes, context, setAttributes, isSelected } ) => {
 	);
 };
 
+/**
+ * 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|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.
+ */
 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 ) {