docs(eng): standardize React hook descriptions for consistency (#207)

yjwhy · web-flow · commit 4a347e489c0d · 2025-05-07T15:32:16.000+09:00
diff --git a/src/hooks/useAsyncEffect/useAsyncEffect.md b/src/hooks/useAsyncEffect/useAsyncEffect.md
@@ -1,6 +1,6 @@
 # useAsyncEffect
 
-`useAsyncEffect` is a custom hook for handling asynchronous side effects in React components. It follows the same cleanup pattern as `useEffect` while ensuring async operations are handled safely.
+`useAsyncEffect` is a React hook for handling asynchronous side effects in React components. It follows the same cleanup pattern as `useEffect` while ensuring async operations are handled safely.
 
 ## Interface
 
diff --git a/src/hooks/useAsyncEffect/useAsyncEffect.ts b/src/hooks/useAsyncEffect/useAsyncEffect.ts
@@ -2,7 +2,7 @@ import { DependencyList, useEffect } from 'react';
 
 /**
  * @description
- * `useAsyncEffect` is a custom hook for handling asynchronous side effects in React components.
+ * `useAsyncEffect` is a React hook for handling asynchronous side effects in React components.
  * It follows the same cleanup pattern as `useEffect` while ensuring async operations are handled safely.
  *
  * @param {() => Promise<void | (() => void)>} [effect] - An asynchronous function executed in the `useEffect` pattern.
diff --git a/src/hooks/useCallbackOncePerRender/useCallbackOncePerRender.md b/src/hooks/useCallbackOncePerRender/useCallbackOncePerRender.md
@@ -1,6 +1,6 @@
 # useCallbackOncePerRender
 
-A React hook that ensures a callback function is executed only once, regardless of how many times it's called. This is useful for one-time operations that should not be repeated, even if the component re-renders.
+`useCallbackOncePerRender` is a React hook that ensures a callback function is executed only once, regardless of how many times it's called. This is useful for one-time operations that should not be repeated, even if the component re-renders.
 
 ## Interface
 
diff --git a/src/hooks/useCallbackOncePerRender/useCallbackOncePerRender.ts b/src/hooks/useCallbackOncePerRender/useCallbackOncePerRender.ts
@@ -5,9 +5,8 @@ import { usePreservedCallback } from '../usePreservedCallback/index.ts';
 
 /**
  * @description
- * A React hook that ensures a callback function is executed only once, regardless of
- * how many times it's called. This is useful for one-time operations that should not
- * be repeated, even if the component re-renders.
+ * `useCallbackOncePerRender` is a React hook that ensures a callback function is executed only once, regardless of how many times it's called.
+ *  This is useful for one-time operations that should not be repeated, even if the component re-renders.
  *
  * @param {() => void} callback - The callback function to be executed once.
  * @param {DependencyList} deps - Dependencies array that will trigger a new one-time execution when changed.
diff --git a/src/hooks/useControlledState/useControlledState.md b/src/hooks/useControlledState/useControlledState.md
@@ -1,6 +1,6 @@
 # useControlledState
 
-`useControlledState` is a hook that allows you to control both controlled and uncontrolled states. If you pass the state to `value`, it will be a controlled state, and if you pass the state to `defaultValue`, it will be an uncontrolled state. If both `value` and `defaultValue` are passed, `value` will take precedence.
+`useControlledState` is a React hook that allows you to control both controlled and uncontrolled states. If you pass the state to `value`, it will be a controlled state, and if you pass the state to `defaultValue`, it will be an uncontrolled state. If both `value` and `defaultValue` are passed, `value` will take precedence.
 
 ## Interface
 
diff --git a/src/hooks/useControlledState/useControlledState.ts b/src/hooks/useControlledState/useControlledState.ts
@@ -9,7 +9,7 @@ export type UseControlledStateProps<T> = ControlledState<T> & {
 
 /**
  * @description
- * `useControlledState` is a hook that allows you to control both controlled and uncontrolled states.
+ * `useControlledState` is a React hook that allows you to control both controlled and uncontrolled states.
  * If you pass the state to `value`, it will be a controlled state, and if you pass the state to `defaultValue`, it will be an uncontrolled state.
  * If both `value` and `defaultValue` are passed, `value` will take precedence.
  *
diff --git a/src/hooks/useDebouncedCallback/useDebouncedCallback.md b/src/hooks/useDebouncedCallback/useDebouncedCallback.md
@@ -1,6 +1,6 @@
 # useDebouncedCallback
 
-`useDebouncedCallback` is a React hook that returns a debounced version of the provided callback function. It helps optimize event handling by delaying function execution and grouping multiple calls into one. Note that if both 'leading' and 'trailing' are included, the function will be called at both the start and end of the delay period. However, it must be called at least twice within debounceMs milliseconds for this to happen, as one debounced function call cannot trigger the function twice.
+`useDebouncedCallback` is a React hook that returns a debounced version of the provided callback function. It helps optimize event handling by delaying function execution and grouping multiple calls into one. Note that if both 'leading' and 'trailing' are set, the function will be called at both the start and end of the delay period. However, it must be called at least twice within debounceMs interval for this to happen, since one debounced function call cannot trigger the function twice.
 
 ## Interface
 
diff --git a/src/hooks/useDebouncedCallback/useDebouncedCallback.ts b/src/hooks/useDebouncedCallback/useDebouncedCallback.ts
@@ -13,7 +13,7 @@ type DebounceOptions = {
  * `useDebouncedCallback` is a React hook that returns a debounced version of the provided callback function.
  * It helps optimize event handling by delaying function execution and grouping multiple calls into one.
  *
- * Note that if both 'leading' and 'trailing' are included, the function will be called at both the start and end of the delay period. However, it must be called at least twice within debounceMs milliseconds for this to happen, as one debounced function call cannot trigger the function twice.
+ * Note that if both 'leading' and 'trailing' are set, the function will be called at both the start and end of the delay period. However, it must be called at least twice within debounceMs interval for this to happen, since one debounced function call cannot trigger the function twice.
  *
  * @param {Object} options - The options object.
  * @param {Function} options.onChange - The callback function to debounce.
diff --git a/src/hooks/useImpressionRef/useImpressionRef.md b/src/hooks/useImpressionRef/useImpressionRef.md
@@ -1,6 +1,6 @@
 # useImpressionRef
 
-`useImpressionRef` is a custom hook that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport. This hook uses `IntersectionObserver` and the `Visibility API` to track the element's visibility.
+`useImpressionRef` is a React hook that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport. It uses `IntersectionObserver` and the `Visibility API` to track the element's visibility.
 
 ## Interface
 
diff --git a/src/hooks/useImpressionRef/useImpressionRef.ts b/src/hooks/useImpressionRef/useImpressionRef.ts
@@ -15,8 +15,8 @@ export type UseImpressionRefOptions = Partial<{
 
 /**
  * @description
- * `useImpressionRef` is a custom hook that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport.
- * This hook uses `IntersectionObserver` and the `Visibility API` to track the element's visibility.
+ * `useImpressionRef` is a React hook that measures the time a specific DOM element is visible on the screen and executes callbacks when the element enters or exits the viewport.
+ * It uses `IntersectionObserver` and the `Visibility API` to track the element's visibility.
  *
  * @param {UseImpressionRefOptions} options - Options for tracking the element's visibility.
  * @param {() => void} [options.onImpressionStart] - Callback function executed when the element enters the view
diff --git a/src/hooks/useIntersectionObserver/useIntersectionObserver.md b/src/hooks/useIntersectionObserver/useIntersectionObserver.md
@@ -1,6 +1,6 @@
 # useIntersectionObserver
 
-`useIntersectionObserver` is a custom hook that detects whether a specific DOM element is visible on the screen. This hook uses the `IntersectionObserver` API to execute a callback when the element enters or exits the viewport.
+`useIntersectionObserver` is a React hook that detects whether a specific DOM element is visible on the screen. It uses the `IntersectionObserver` API to execute a callback when the element enters or exits the viewport.
 
 ## Interface
 
diff --git a/src/hooks/useIntersectionObserver/useIntersectionObserver.ts b/src/hooks/useIntersectionObserver/useIntersectionObserver.ts
@@ -5,8 +5,8 @@ import { useRefEffect } from '../useRefEffect/index.ts';
 
 /**
  * @description
- * `useIntersectionObserver` is a custom hook that detects whether a specific DOM element is visible on the screen.
- * This hook uses the `IntersectionObserver` API to execute a callback when the element enters or exits the viewport.
+ * `useIntersectionObserver` is a React hook that detects whether a specific DOM element is visible on the screen.
+ * It uses the `IntersectionObserver` API to execute a callback when the element enters or exits the viewport.
  *
  * @param {(entry: IntersectionObserverEntry) => void} callback - A callback function that is executed when the visibility of the element changes.
  *   You can check `entry.isIntersecting` to determine if the element is in view.
diff --git a/src/hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect.md b/src/hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect.md
@@ -1,6 +1,12 @@
 # useIsomorphicLayoutEffect
 
-During SSR, there is no DOM to synchronously measure or mutate, so React warns about using useLayoutEffect. This hook provides the behavior of useLayoutEffect in the browser without triggering SSR warnings. It runs synchronously after DOM updates but before paint, making it ideal for: - Measuring DOM elements after render - Applying DOM changes before paint - Preventing UI flashes or layout shifts - Supporting both client and server environments safely
+`useIsomorphicLayoutEffect` is a React hook that provides the behavior of `useLayoutEffect` without triggering warnings during server-side rendering. During SSR, there is no DOM to synchronously measure or mutate, so React warns about using `useLayoutEffect`. 
+
+This hook runs synchronously after DOM updates but before paint, making it ideal for: 
+- Measuring DOM elements after render
+- Applying DOM changes before paint
+- Preventing UI flashes or layout shifts
+- Supporting both client and server environments
 
 ## Interface
 
diff --git a/src/hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect.ts b/src/hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect.ts
@@ -4,11 +4,10 @@ const isServer = typeof window === 'undefined';
 
 /**
  * @description
- * During SSR, there is no DOM to synchronously measure or mutate, so React warns about using useLayoutEffect.
+ * `useIsomorphicLayoutEffect` is a React hook that provides the behavior of `useLayoutEffect` without triggering warnings during server-side rendering.
+ * During SSR, there is no DOM to synchronously measure or mutate, so React warns about using `useLayoutEffect`.
  *
- * This hook provides the behavior of useLayoutEffect in the browser without triggering SSR warnings.
- *
- * It runs synchronously after DOM updates but before paint, making it ideal for:
+ * This hook runs synchronously after DOM updates but before paint, making it ideal for:
  * - Measuring DOM elements after render
  * - Applying DOM changes before paint
  * - Preventing UI flashes or layout shifts
diff --git a/src/hooks/usePrevious/usePrevious.md b/src/hooks/usePrevious/usePrevious.md
@@ -1,6 +1,6 @@
 # usePrevious
 
-Returns the previous value of the input state. If a re-render occurs but the state value does not change, the previous value remains unchanged. If the state is an object or requires custom change detection, a `compare` function can be provided. By default, state changes are detected using `prev === next`.
+`usePrevious` is a React hook that returns the previous value of the input state. It preserves the previous value unchanged when re-render occur without state changes. If the state is an object or requires custom change detection, a `compare` function can be provided. By default, state changes are detected using `prev === next`.
 
 ## Interface
 
diff --git a/src/hooks/usePrevious/usePrevious.ts b/src/hooks/usePrevious/usePrevious.ts
@@ -4,8 +4,8 @@ const strictEquals = <T>(prev: T | undefined, next: T) => prev === next;
 
 /**
  * @description
- * Returns the previous value of the input state.
- * If a re-render occurs but the state value does not change, the previous value remains unchanged.
+ * `usePrevious` is a React hook that returns the previous value of the input state.
+ * It preserves the previous value unchanged when re-render occur without state changes.
  * If the state is an object or requires custom change detection, a `compare` function can be provided.
  * By default, state changes are detected using `prev === next`.
  *
diff --git a/src/hooks/useRefEffect/useRefEffect.md b/src/hooks/useRefEffect/useRefEffect.md
@@ -1,6 +1,6 @@
 # useRefEffect
 
-`useRefEffect` is a custom hook that helps you set a reference to a specific DOM element and execute a callback whenever the element changes. This hook calls a cleanup function whenever the element changes to prevent memory leaks.
+`useRefEffect` is a React hook that helps you set a reference to a specific DOM element and execute a callback whenever the element changes. This hook calls a cleanup function whenever the element changes to prevent memory leaks.
 
 ## Interface
 
diff --git a/src/hooks/useRefEffect/useRefEffect.ts b/src/hooks/useRefEffect/useRefEffect.ts
@@ -6,7 +6,7 @@ export type CleanupCallback = () => void;
 
 /**
  * @description
- * `useRefEffect` is a custom hook that helps you set a reference to a specific DOM element and execute a callback whenever the element changes.
+ * `useRefEffect` is a React hook that helps you set a reference to a specific DOM element and execute a callback whenever the element changes.
  * This hook calls a cleanup function whenever the element changes to prevent memory leaks.
  *
  * @param {(element: Element) => CleanupCallback | void} callback - A callback function that is executed when the element is set. This function can return a cleanup function.
diff --git a/src/hooks/useStorageState/useStorageState.md b/src/hooks/useStorageState/useStorageState.md
@@ -1,6 +1,6 @@
 # useStorageState
 
-A React hook that functions like `useState` but persists the state value in browser storage. The value is retained across page reloads and can be shared between tabs when using `localStorage`.
+`useStorageState` is a React hook that functions like `useState` but persists the state value in browser storage. The value is retained across page reloads and can be shared between tabs when using `localStorage`.
 
 ## Interface
 
diff --git a/src/hooks/useStorageState/useStorageState.ts b/src/hooks/useStorageState/useStorageState.ts
@@ -63,7 +63,7 @@ const ensureSerializable = <T extends readonly any[]>(value: T): SerializableGua
 
 /**
  * @description
- * A React hook that functions like `useState` but persists the state value in browser storage.
+ * `useStorageState` is a React that functions like `useState` but persists the state value in browser storage.
  * The value is retained across page reloads and can be shared between tabs when using `localStorage`.
  *
  * @param {string} key - The key used to store the value in storage.
diff --git a/src/hooks/useThrottle/useThrottle.md b/src/hooks/useThrottle/useThrottle.md
@@ -1,6 +1,6 @@
 # useThrottle
 
-A React hook that creates a throttled version of a callback function. This is useful for limiting the rate at which a function can be called, such as when handling scroll or resize events.
+`useThrottle` is a React hook that creates a throttled version of a callback function. This is useful for limiting the rate at which a function can be called, such as when handling scroll or resize events.
 
 ## Interface
 
diff --git a/src/hooks/useThrottle/useThrottle.ts b/src/hooks/useThrottle/useThrottle.ts
@@ -8,7 +8,7 @@ import { throttle } from './throttle.ts';
 
 /**
  * @description
- * A React hook that creates a throttled version of a callback function.
+ * `useThrottle` is a React hook that creates a throttled version of a callback function.
  * This is useful for limiting the rate at which a function can be called,
  * such as when handling scroll or resize events.
  *
diff --git a/src/hooks/useVisibilityEvent/useVisibilityEvent.md b/src/hooks/useVisibilityEvent/useVisibilityEvent.md
@@ -1,6 +1,6 @@
 # useVisibilityEvent
 
-A React hook that listens to changes in the document's visibility state and triggers a callback.
+`useVisibilityEvent` is a React hook that listens to changes in the document's visibility state and triggers a callback.
 
 ## Interface
 
diff --git a/src/hooks/useVisibilityEvent/useVisibilityEvent.ts b/src/hooks/useVisibilityEvent/useVisibilityEvent.ts
@@ -6,7 +6,7 @@ type Options = {
 
 /**
  * @description
- * A React hook that listens to changes in the document's visibility state and triggers a callback.
+ * `useVisibilityEvent` is a React hook that listens to changes in the document's visibility state and triggers a callback.
  *
  * @param {(visibilityState: 'visible' | 'hidden') => void} callback - A function to be called
  * when the visibility state changes. It receives the current visibility state ('visible' or 'hidden') as an argument.

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@ import { DependencyList, useEffect } from 'react';`
`2`	`2`
`3`	`3`	`/**`
`4`	`4`	`* @description`
`5`		- * `useAsyncEffect` is a custom hook for handling asynchronous side effects in React components.
	`5`	+ * `useAsyncEffect` is a React hook for handling asynchronous side effects in React components.
`6`	`6`	* It follows the same cleanup pattern as `useEffect` while ensuring async operations are handled safely.
`7`	`7`	`*`
`8`	`8`	* @param {() => Promise<void \| (() => void)>} [effect] - An asynchronous function executed in the `useEffect` pattern.
Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ export type UseControlledStateProps<T> = ControlledState<T> & {`
`9`	`9`
`10`	`10`	`/**`
`11`	`11`	`* @description`
`12`		- * `useControlledState` is a hook that allows you to control both controlled and uncontrolled states.
	`12`	+ * `useControlledState` is a React hook that allows you to control both controlled and uncontrolled states.
`13`	`13`	* If you pass the state to `value`, it will be a controlled state, and if you pass the state to `defaultValue`, it will be an uncontrolled state.
`14`	`14`	* If both `value` and `defaultValue` are passed, `value` will take precedence.
`15`	`15`	`*`
Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,7 @@ type DebounceOptions = {`
`13`	`13`	* `useDebouncedCallback` is a React hook that returns a debounced version of the provided callback function.
`14`	`14`	`* It helps optimize event handling by delaying function execution and grouping multiple calls into one.`
`15`	`15`	`*`
`16`		`- * Note that if both 'leading' and 'trailing' are included, the function will be called at both the start and end of the delay period. However, it must be called at least twice within debounceMs milliseconds for this to happen, as one debounced function call cannot trigger the function twice.`
	`16`	`+ * Note that if both 'leading' and 'trailing' are set, the function will be called at both the start and end of the delay period. However, it must be called at least twice within debounceMs interval for this to happen, since one debounced function call cannot trigger the function twice.`
`17`	`17`	`*`
`18`	`18`	`* @param {Object} options - The options object.`
`19`	`19`	`* @param {Function} options.onChange - The callback function to debounce.`