From 1f4ecb5a455203907fc21a79c49008bfd15b75e0 Mon Sep 17 00:00:00 2001 From: Brian Gosnell Date: Thu, 16 May 2024 11:31:30 -0500 Subject: [PATCH 1/3] Add jsdoc to post-visibiltiy Co-authored-by: dbrian --- packages/editor/README.md | 40 +++++++++++++++++-- .../src/components/post-visibility/check.js | 11 +++++ .../src/components/post-visibility/index.js | 21 ++++++++++ .../src/components/post-visibility/label.js | 12 ++++++ 4 files changed, 80 insertions(+), 4 deletions(-) diff --git a/packages/editor/README.md b/packages/editor/README.md index 48a5e52cc47aa..cec58729459fa 100644 --- a/packages/editor/README.md +++ b/packages/editor/README.md @@ -1154,15 +1154,43 @@ Undocumented declaration. ### PostVisibility -Undocumented declaration. +PostVisibility component. + +Allows users to set the visibility of a post. + +_Parameters_ + +- _props_ `Object`: Component properties. +- _props.onClose_ `Function`: Function to call when the popover is closed. + +_Returns_ + +- `JSX.Element`: The rendered component. ### PostVisibilityCheck -Undocumented declaration. +PostVisibilityCheck component. + +Determines if the current post can be edited (published) and passes this information to the provided render function. + +_Parameters_ + +- _props_ `Object`: - Component properties. +- _props.render_ `Function`: - Function to render the component. Receives an object with a `canEdit` property. + +_Returns_ + +- `JSX.Element`: Rendered component. ### PostVisibilityLabel -Undocumented declaration. +PostVisibilityLabel component. + +Returns the label for the current post visibility setting. + +_Returns_ + +- `string`: Post visibility label. ### privateApis @@ -1266,7 +1294,11 @@ Undocumented declaration. ### usePostVisibilityLabel -Undocumented declaration. +Get the label for the current post visibility setting. + +_Returns_ + +- `string`: Post visibility label. ### userAutocompleter diff --git a/packages/editor/src/components/post-visibility/check.js b/packages/editor/src/components/post-visibility/check.js index 116db0f546de2..3de7b715b2117 100644 --- a/packages/editor/src/components/post-visibility/check.js +++ b/packages/editor/src/components/post-visibility/check.js @@ -8,6 +8,17 @@ import { useSelect } from '@wordpress/data'; */ import { store as editorStore } from '../../store'; +/** + * PostVisibilityCheck component. + * + * Determines if the current post can be edited (published) + * and passes this information to the provided render function. + * + * @param {Object} props - Component properties. + * @param {Function} props.render - Function to render the component. + * Receives an object with a `canEdit` property. + * @return {JSX.Element} Rendered component. + */ export default function PostVisibilityCheck( { render } ) { const canEdit = useSelect( ( select ) => { return ( diff --git a/packages/editor/src/components/post-visibility/index.js b/packages/editor/src/components/post-visibility/index.js index 0dde8905cbb36..91358908d4e54 100644 --- a/packages/editor/src/components/post-visibility/index.js +++ b/packages/editor/src/components/post-visibility/index.js @@ -17,6 +17,15 @@ import { __experimentalInspectorPopoverHeader as InspectorPopoverHeader } from ' import { visibilityOptions } from './utils'; import { store as editorStore } from '../../store'; +/** + * PostVisibility component. + * + * Allows users to set the visibility of a post. + * + * @param {Object} props Component properties. + * @param {Function} props.onClose Function to call when the popover is closed. + * @return {JSX.Element} The rendered component. + */ export default function PostVisibility( { onClose } ) { const instanceId = useInstanceId( PostVisibility ); @@ -133,6 +142,18 @@ export default function PostVisibility( { onClose } ) { ); } +/** + * PostVisibilityChoice component. + * + * Renders a visibility choice option. + * + * @param {Object} props - Component properties. + * @param {number} props.instanceId - Unique instance ID for the component. + * @param {string} props.value - The value of the visibility option. + * @param {string} props.label - The label for the visibility option. + * @param {string} props.info - Additional information about the visibility option. + * @return {JSX.Element} The rendered component. + */ function PostVisibilityChoice( { instanceId, value, label, info, ...props } ) { return (
diff --git a/packages/editor/src/components/post-visibility/label.js b/packages/editor/src/components/post-visibility/label.js index 580eed75620b4..abbdd37c9bafc 100644 --- a/packages/editor/src/components/post-visibility/label.js +++ b/packages/editor/src/components/post-visibility/label.js @@ -9,10 +9,22 @@ import { useSelect } from '@wordpress/data'; import { visibilityOptions } from './utils'; import { store as editorStore } from '../../store'; +/** + * PostVisibilityLabel component. + * + * Returns the label for the current post visibility setting. + * + * @return {string} Post visibility label. + */ export default function PostVisibilityLabel() { return usePostVisibilityLabel(); } +/** + * Get the label for the current post visibility setting. + * + * @return {string} Post visibility label. + */ export function usePostVisibilityLabel() { const visibility = useSelect( ( select ) => select( editorStore ).getEditedPostVisibility() From 097537ea3a4c2755cf78663c41a25c4e4e77ea8b Mon Sep 17 00:00:00 2001 From: Damon Cook Date: Fri, 17 May 2024 18:15:55 -0400 Subject: [PATCH 2/3] Refine PostVisibitly editor component JSDocs --- .../src/components/post-visibility/check.js | 8 +++----- .../src/components/post-visibility/index.js | 16 +--------------- .../src/components/post-visibility/label.js | 2 -- 3 files changed, 4 insertions(+), 22 deletions(-) diff --git a/packages/editor/src/components/post-visibility/check.js b/packages/editor/src/components/post-visibility/check.js index 3de7b715b2117..19a241ae1110a 100644 --- a/packages/editor/src/components/post-visibility/check.js +++ b/packages/editor/src/components/post-visibility/check.js @@ -9,15 +9,13 @@ import { useSelect } from '@wordpress/data'; import { store as editorStore } from '../../store'; /** - * PostVisibilityCheck component. - * * Determines if the current post can be edited (published) * and passes this information to the provided render function. * - * @param {Object} props - Component properties. - * @param {Function} props.render - Function to render the component. + * @param {Object} props The component props. + * @param {Function} props.render Function to render the component. * Receives an object with a `canEdit` property. - * @return {JSX.Element} Rendered component. + * @return {JSX.Element} The rendered component. */ export default function PostVisibilityCheck( { render } ) { const canEdit = useSelect( ( select ) => { diff --git a/packages/editor/src/components/post-visibility/index.js b/packages/editor/src/components/post-visibility/index.js index 91358908d4e54..fef07d0033d36 100644 --- a/packages/editor/src/components/post-visibility/index.js +++ b/packages/editor/src/components/post-visibility/index.js @@ -18,11 +18,9 @@ import { visibilityOptions } from './utils'; import { store as editorStore } from '../../store'; /** - * PostVisibility component. - * * Allows users to set the visibility of a post. * - * @param {Object} props Component properties. + * @param {Object} props The component props. * @param {Function} props.onClose Function to call when the popover is closed. * @return {JSX.Element} The rendered component. */ @@ -142,18 +140,6 @@ export default function PostVisibility( { onClose } ) { ); } -/** - * PostVisibilityChoice component. - * - * Renders a visibility choice option. - * - * @param {Object} props - Component properties. - * @param {number} props.instanceId - Unique instance ID for the component. - * @param {string} props.value - The value of the visibility option. - * @param {string} props.label - The label for the visibility option. - * @param {string} props.info - Additional information about the visibility option. - * @return {JSX.Element} The rendered component. - */ function PostVisibilityChoice( { instanceId, value, label, info, ...props } ) { return (
diff --git a/packages/editor/src/components/post-visibility/label.js b/packages/editor/src/components/post-visibility/label.js index abbdd37c9bafc..50a6e14aa1a14 100644 --- a/packages/editor/src/components/post-visibility/label.js +++ b/packages/editor/src/components/post-visibility/label.js @@ -10,8 +10,6 @@ import { visibilityOptions } from './utils'; import { store as editorStore } from '../../store'; /** - * PostVisibilityLabel component. - * * Returns the label for the current post visibility setting. * * @return {string} Post visibility label. From ade7184f5878de274a35862bfd7b360de7f8dbb9 Mon Sep 17 00:00:00 2001 From: Damon Cook Date: Fri, 17 May 2024 18:16:38 -0400 Subject: [PATCH 3/3] Auto-generate PostVisibility component docs --- packages/editor/README.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/packages/editor/README.md b/packages/editor/README.md index cec58729459fa..2558307be0204 100644 --- a/packages/editor/README.md +++ b/packages/editor/README.md @@ -1154,13 +1154,11 @@ Undocumented declaration. ### PostVisibility -PostVisibility component. - Allows users to set the visibility of a post. _Parameters_ -- _props_ `Object`: Component properties. +- _props_ `Object`: The component props. - _props.onClose_ `Function`: Function to call when the popover is closed. _Returns_ @@ -1169,23 +1167,19 @@ _Returns_ ### PostVisibilityCheck -PostVisibilityCheck component. - Determines if the current post can be edited (published) and passes this information to the provided render function. _Parameters_ -- _props_ `Object`: - Component properties. -- _props.render_ `Function`: - Function to render the component. Receives an object with a `canEdit` property. +- _props_ `Object`: The component props. +- _props.render_ `Function`: Function to render the component. Receives an object with a `canEdit` property. _Returns_ -- `JSX.Element`: Rendered component. +- `JSX.Element`: The rendered component. ### PostVisibilityLabel -PostVisibilityLabel component. - Returns the label for the current post visibility setting. _Returns_