Move documentation to the hook

WordPress · Dec 14, 2021 · ee8881f · ee8881f
1 parent 57461d4
commit ee8881f
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 31 deletions.
diff --git 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
@@ -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 = () => {