From a435f8140a94f8e888465cd20e48c0d27a338261 Mon Sep 17 00:00:00 2001
From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com>
Date: Mon, 11 Jul 2022 12:58:36 +1000
Subject: [PATCH] Tweak JSDoc comments and typing

---
 .../components/src/range-control/types.ts     | 45 +++++++++++++++++
 .../components/src/range-control/utils.ts     | 48 ++++++++-----------
 2 files changed, 66 insertions(+), 27 deletions(-)

diff --git a/packages/components/src/range-control/types.ts b/packages/components/src/range-control/types.ts
index e3039933d26c32..1e2e4350870b07 100644
--- a/packages/components/src/range-control/types.ts
+++ b/packages/components/src/range-control/types.ts
@@ -269,12 +269,57 @@ export type TrackProps = {
 };
 
 export type useControlledRangeValueArgs = {
+	/**
+	 * The initial value.
+	 */
 	initial?: number;
+	/**
+	 * The maximum value.
+	 */
 	max: number;
+	/**
+	 * The minimum value.
+	 */
 	min: number;
+	/**
+	 * The current value.
+	 */
 	value: number | null;
 };
 
+export type useDebouncedHoverInteractionArgs = {
+	/**
+	 *  A callback function invoked when the element is hidden.
+	 *
+	 * @default () => {}
+	 */
+	onHide?: () => void;
+	/**
+	 * A callback function invoked when the mouse is moved out of the element.
+	 *
+	 * @default () => {}
+	 */
+	onMouseLeave?: MouseEventHandler< HTMLInputElement >;
+	/**
+	 * A callback function invoked when the mouse is moved.
+	 *
+	 * @default () => {}
+	 */
+	onMouseMove?: MouseEventHandler< HTMLInputElement >;
+	/**
+	 * A callback function invoked when the element is shown.
+	 *
+	 * @default () => {}
+	 */
+	onShow?: () => void;
+	/**
+	 * Timeout before the element is shown or hidden.
+	 *
+	 * @default 300
+	 */
+	timeout?: number;
+};
+
 export type useMarksArgs = NumericProps & {
 	marks: RangeMarks;
 	step: number;
diff --git a/packages/components/src/range-control/utils.ts b/packages/components/src/range-control/utils.ts
index 8a331f14676c95..cc2430b7bf06cf 100644
--- a/packages/components/src/range-control/utils.ts
+++ b/packages/components/src/range-control/utils.ts
@@ -14,7 +14,10 @@ import { useCallback, useRef, useEffect, useState } from '@wordpress/element';
 import { useControlledState } from '../utils/hooks';
 import { clamp } from '../utils/math';
 
-import type { useControlledRangeValueArgs } from './types';
+import type {
+	useControlledRangeValueArgs,
+	useDebouncedHoverInteractionArgs,
+} from './types';
 
 const noop = () => {};
 
@@ -38,20 +41,13 @@ export function floatClamp( value: number | null, min: number, max: number ) {
 /**
  * Hook to store a clamped value, derived from props.
  *
- * @param  settings         Hook settings.
- * @param  settings.min     The minimum value.
- * @param  settings.max     The maximum value.
- * @param  settings.value   The current value.
- * @param  settings.initial The initial value.
- *
+ * @param  settings
  * @return The controlled value and the value setter.
  */
-export function useControlledRangeValue( {
-	min,
-	max,
-	value: valueProp,
-	initial,
-}: useControlledRangeValueArgs ) {
+export function useControlledRangeValue(
+	settings: useControlledRangeValueArgs
+) {
+	const { min, max, value: valueProp, initial } = settings;
 	const [ state, setInternalState ] = useControlledState(
 		floatClamp( valueProp, min, max ),
 		{ initial, fallback: null }
@@ -77,22 +73,20 @@ export function useControlledRangeValue( {
  * Hook to encapsulate the debouncing "hover" to better handle the showing
  * and hiding of the Tooltip.
  *
- * @param  settings                     Hook settings.
- * @param  [settings.onShow=noop]       A callback function invoked when the element is shown.
- * @param  [settings.onHide=noop]       A callback function invoked when the element is hidden.
- * @param  [settings.onMouseMove=noop]  A callback function invoked when the mouse is moved.
- * @param  [settings.onMouseLeave=noop] A callback function invoked when the mouse is moved out of the element.
- * @param  [settings.timeout=300]       Timeout before the element is shown or hidden.
- *
+ * @param  settings
  * @return Bound properties for use on a React.Node.
  */
-export function useDebouncedHoverInteraction( {
-	onHide = noop,
-	onMouseLeave = noop as MouseEventHandler,
-	onMouseMove = noop as MouseEventHandler,
-	onShow = noop,
-	timeout = 300,
-} ) {
+export function useDebouncedHoverInteraction(
+	settings: useDebouncedHoverInteractionArgs
+) {
+	const {
+		onHide = noop,
+		onMouseLeave = noop as MouseEventHandler,
+		onMouseMove = noop as MouseEventHandler,
+		onShow = noop,
+		timeout = 300,
+	} = settings;
+
 	const [ show, setShow ] = useState( false );
 	const timeoutRef = useRef< number | undefined >();