Documentation: Add PostURL component docs (WordPress#61737)

* Add JSDoc dockblock for PostURL component * Refine PostURL JSDocs * Add PostURLPanel JSDocs * Add PostURLLabel JSDocs * Add PostURLCheck JSDocs * Auto-generate editor docs for PostURL updates --------- Co-authored-by: Damon Cook <[email protected]>
carstingaxion · May 21, 2024 · 538f18d · 538f18d
1 parent f22e423
commit 538f18d
Show file tree

Hide file tree

Showing 5 changed files with 75 additions and 5 deletions.
diff --git a/packages/editor/README.md b/packages/editor/README.md
@@ -1207,19 +1207,50 @@ _Returns_
 
 ### PostURL
 
-Undocumented declaration.
+Renders the `PostURL` component.
+
+_Usage_
+
+```jsx
+<PostURL />
+```
+
+_Parameters_
+
+-   _onClose_ `Function`: Callback function to be executed when the popover is closed.
+
+_Returns_
+
+-   `Component`: The rendered PostURL component.
 
 ### PostURLCheck
 
-Undocumented declaration.
+Check if the post URL is valid and visible.
+
+_Parameters_
+
+-   _props_ `Object`: The component props.
+-   _props.children_ `Element`: The child components.
+
+_Returns_
+
+-   `Component|null`: The child components if the post URL is valid and visible, otherwise null.
 
 ### PostURLLabel
 
-Undocumented declaration.
+Represents a label component for a post URL.
+
+_Returns_
+
+-   `Component`: The PostURLLabel component.
 
 ### PostURLPanel
 
-Undocumented declaration.
+Renders the `PostURLPanel` component.
+
+_Returns_
+
+-   `JSX.Element`: The rendered PostURLPanel component.
 
 ### PostVisibility
 
@@ -1362,7 +1393,11 @@ _Returns_
 
 ### usePostURLLabel
 
-Undocumented declaration.
+Custom hook to get the label for the post URL.
+
+_Returns_
+
+-   `string`: The filtered and decoded post URL label.
 
 ### usePostVisibilityLabel
 

diff --git a/packages/editor/src/components/post-url/check.js b/packages/editor/src/components/post-url/check.js
@@ -9,6 +9,14 @@ import { store as coreStore } from '@wordpress/core-data';
  */
 import { store as editorStore } from '../../store';
 
+/**
+ * Check if the post URL is valid and visible.
+ *
+ * @param {Object}  props          The component props.
+ * @param {Element} props.children The child components.
+ *
+ * @return {Component|null} The child components if the post URL is valid and visible, otherwise null.
+ */
 export default function PostURLCheck( { children } ) {
 	const isVisible = useSelect( ( select ) => {
 		const postTypeSlug = select( editorStore ).getCurrentPostType();

diff --git a/packages/editor/src/components/post-url/index.js b/packages/editor/src/components/post-url/index.js
@@ -24,6 +24,18 @@ import { useCopyToClipboard } from '@wordpress/compose';
 import { usePostURLLabel } from './label';
 import { store as editorStore } from '../../store';
 
+/**
+ * Renders the `PostURL` component.
+ *
+ * @example
+ * ```jsx
+ * <PostURL />
+ * ```
+ *
+ * @param {Function} onClose Callback function to be executed when the popover is closed.
+ *
+ * @return {Component} The rendered PostURL component.
+ */
 export default function PostURL( { onClose } ) {
 	const { isEditable, postSlug, postLink, permalinkPrefix, permalinkSuffix } =
 		useSelect( ( select ) => {

diff --git a/packages/editor/src/components/post-url/label.js b/packages/editor/src/components/post-url/label.js
@@ -9,10 +9,20 @@ import { filterURLForDisplay, safeDecodeURIComponent } from '@wordpress/url';
  */
 import { store as editorStore } from '../../store';
 
+/**
+ * Represents a label component for a post URL.
+ *
+ * @return {Component} The PostURLLabel component.
+ */
 export default function PostURLLabel() {
 	return usePostURLLabel();
 }
 
+/**
+ * Custom hook to get the label for the post URL.
+ *
+ * @return {string} The filtered and decoded post URL label.
+ */
 export function usePostURLLabel() {
 	const postLink = useSelect(
 		( select ) => select( editorStore ).getPermalink(),

diff --git a/packages/editor/src/components/post-url/panel.js b/packages/editor/src/components/post-url/panel.js
@@ -15,6 +15,11 @@ import PostURL from './index';
 import PostPanelRow from '../post-panel-row';
 import { store as editorStore } from '../../store';
 
+/**
+ * Renders the `PostURLPanel` component.
+ *
+ * @return {JSX.Element} The rendered PostURLPanel component.
+ */
 export default function PostURLPanel() {
 	// Use internal state instead of a ref to make sure that the component
 	// re-renders when the popover's anchor updates.