From ee8881f029940d66ebdead8a0ded7ef57f12fcfb Mon Sep 17 00:00:00 2001
From: Andrew Serong <14988353+andrewserong@users.noreply.github.com>
Date: Tue, 14 Dec 2021 16:46:26 +1100
Subject: [PATCH] Move documentation to the hook

---
 packages/compose/README.md                    | 30 -------------------
 .../compose/src/hooks/use-disabled/index.js   | 23 +++++++++++++-
 2 files changed, 22 insertions(+), 31 deletions(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index 4e75f92e1738b..32c8abb4e3bd0 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -209,36 +209,6 @@ _Returns_
 
 -   `import('lodash').DebouncedFunc<TFunc>`: Debounced function.
 
-### __experimentalUseDisabled
-
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
-In some circumstances, such as block previews, all focusable DOM elements
-(input fields, links, buttons, etc.) need to be disabled. This hook adds the
-behavior to disable nested DOM elements to the returned ref.
-
-_Usage_
-
-```js
-import { __experimentalUseDisabled as useDisabled } from '@wordpress/compose';
-
-const DisabledExample = () => {
-	const disabledRef = useDisabled();
-	return (
-		<div ref={ disabledRef }>
-			<a href="#">This link will have tabindex set to -1</a>
-			<input placeholder="This input will have the disabled attribute added to it." type="text" />
-		</div>
-	);
-};
-```
-
-_Returns_
-
--   `import('react').RefCallback<Element>`: Element Ref.
-
 ### useFocusableIframe
 
 Dispatches a bubbling focus event when the iframe receives focus. Use
diff --git a/packages/compose/src/hooks/use-disabled/index.js b/packages/compose/src/hooks/use-disabled/index.js
index dce96a0a9d8b9..8cb44e39a6798 100644
--- a/packages/compose/src/hooks/use-disabled/index.js
+++ b/packages/compose/src/hooks/use-disabled/index.js
@@ -28,8 +28,29 @@ const DISABLED_ELIGIBLE_NODE_NAMES = [
 	'TEXTAREA',
 ];
 
+/**
+ * In some circumstances, such as block previews, all focusable DOM elements
+ * (input fields, links, buttons, etc.) need to be disabled. This hook adds the
+ * behavior to disable nested DOM elements to the returned ref.
+ *
+ * @return {import('react').RefObject<HTMLElement>} Element Ref.
+ *
+ * @example
+ * ```js
+ * import { __experimentalUseDisabled as useDisabled } from '@wordpress/compose';
+ * const DisabledExample = () => {
+ * 	const disabledRef = useDisabled();
+ *	return (
+ *		<div ref={ disabledRef }>
+ *			<a href="#">This link will have tabindex set to -1</a>
+ *			<input placeholder="This input will have the disabled attribute added to it." type="text" />
+ *		</div>
+ *	);
+ * };
+ * ```
+ */
 export default function useDisabled() {
-	/** @type {import('react').RefObject<HTMLDivElement>} */
+	/** @type {import('react').RefObject<HTMLElement>} */
 	const node = useRef( null );
 
 	const disable = () => {