From 538f18dc7fcfc6c06a9332e2c674fa8762d95976 Mon Sep 17 00:00:00 2001
From: Kellen Mace <kellen.mace@gmail.com>
Date: Tue, 21 May 2024 17:40:05 -0400
Subject: [PATCH] Documentation: Add PostURL component docs (#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 <damonacook@gmail.com>
---
 packages/editor/README.md                     | 45 ++++++++++++++++---
 .../editor/src/components/post-url/check.js   |  8 ++++
 .../editor/src/components/post-url/index.js   | 12 +++++
 .../editor/src/components/post-url/label.js   | 10 +++++
 .../editor/src/components/post-url/panel.js   |  5 +++
 5 files changed, 75 insertions(+), 5 deletions(-)

diff --git a/packages/editor/README.md b/packages/editor/README.md
index 1fdb1d0918f5a..2997ac0c2d420 100644
--- 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
index 65c54846a702b..7eb390472bdd7 100644
--- 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
index cf55e30473329..9453977a23bf0 100644
--- 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
index 5c233dfd54946..4f03e2bce0d05 100644
--- 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
index c4a1cbba935c7..fbf174cc28bf3 100644
--- 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.