chore: add jsdoc info

packages/hooks/src/useAntdTable/index.tsx

@@ -12,6 +12,10 @@ import type {
  AntdTableResult,
 } from './types';
 
+/**
+ * `useAntdTable` is implemented based on [useRequest](https://ahooks.js.org/hooks/use-request) and encapsulates the commonly used [Ant Design Form](https://ant.design/components/form/) and [Ant Design Table](https://ant.design/components/table/) data binding logic, and supports both antd v3 and v4.
+ * @see https://ahooks.js.org/hooks/use-antd-table
+ */
 const useAntdTable = <TData extends Data, TParams extends Params>(
  service: Service<TData, TParams>,
  options: AntdTableOptions<TData, TParams> = {},

packages/hooks/src/useAsyncEffect/index.ts

@@ -8,6 +8,10 @@ function isAsyncGenerator(
  return isFunction(val[Symbol.asyncIterator]);
 }
 
+/**
+ * useEffect support async function.
+ * @see https://ahooks.js.org/hooks/use-async-effect
+ */
 function useAsyncEffect(
  effect: () => AsyncGenerator<void, void, void> | Promise<void>,
  deps?: DependencyList,

packages/hooks/src/useBoolean/index.ts

@@ -8,6 +8,14 @@ export interface Actions {
  toggle: () => void;
 }
 
+/**
+ * Elegantly manages boolean state.
+ * @see https://ahooks.js.org/hooks/use-boolean
+ * @example
+ * ```jsx
+ * const [state, { toggle, setTrue, setFalse }] = useBoolean(true);
+ * ```
+ */
 export default function useBoolean(defaultValue = false): [boolean, Actions] {
  const [state, { toggle, set }] = useToggle(!!defaultValue);
 

packages/hooks/src/useClickAway/index.ts

@@ -6,6 +6,10 @@ import useEffectWithTarget from '../utils/useEffectWithTarget';
 
 type DocumentEventKey = keyof DocumentEventMap;
 
+/**
+ * Listen for click events outside the target element.
+ * @see https://ahooks.js.org/hooks/use-click-away
+ */
 export default function useClickAway<T extends Event = Event>(
  onClickAway: (event: T) => void,
  target: BasicTarget | BasicTarget[],

packages/hooks/src/useControllableValue/index.ts

@@ -19,6 +19,10 @@ export interface StandardProps<T> {
  onChange: (val: T) => void;
 }
 
+/**
+ * Controlled and uncontrolled
+ * @see https://ahooks.js.org/hooks/use-controllable-value)
+ */
 function useControllableValue<T = any>(
  props: StandardProps<T>,
 ): [T, (v: SetStateAction<T>) => void];

packages/hooks/src/useCookieState/index.ts

@@ -9,6 +9,10 @@ export interface Options extends Cookies.CookieAttributes {
  defaultValue?: State | (() => State);
 }
 
+/**
+ * A Hook that store state into Cookie.
+ * @see https://ahooks.js.org/hooks/use-cookie-state
+ */
 function useCookieState(cookieKey: string, options: Options = {}) {
  const [state, setState] = useState<State>(() => {
  const cookieValue = Cookies.get(cookieKey);

packages/hooks/src/useCountDown/index.ts

@@ -39,6 +39,10 @@ const parseMs = (milliseconds: number): FormattedRes => {
  };
 };
 
+/**
+ * A hook for manage countdown.
+ * @see https://ahooks.js.org/hooks/use-count-down
+ */
 const useCountdown = (options: Options = {}) => {
  const { leftTime, targetDate, interval = 1000, onEnd } = options || {};
 

packages/hooks/src/useCounter/index.ts

@@ -28,6 +28,10 @@ function getTargetValue(val: number, options: Options = {}) {
  return target;
 }
 
+/**
+ * A hook that manage counter.
+ * @see https://ahooks.js.org/hooks/use-counter
+ */
 function useCounter(initialValue: number = 0, options: Options = {}) {
  const { min, max } = options;
 

packages/hooks/src/useCreation/index.ts

@@ -2,6 +2,10 @@ import type { DependencyList } from 'react';
 import { useRef } from 'react';
 import depsAreSame from '../utils/depsAreSame';
 
+/**
+ * `useCreation` is the replacement for `useMemo` or `useRef`.
+ * @see https://ahooks.js.org/hooks/use-creation
+ */
 export default function useCreation<T>(factory: () => T, deps: DependencyList) {
  const { current } = useRef({
  deps,

packages/hooks/src/useDebounce/index.ts

@@ -2,6 +2,10 @@ import { useEffect, useState } from 'react';
 import useDebounceFn from '../useDebounceFn';
 import type { DebounceOptions } from './debounceOptions';
 
+/**
+ * A hook that deal with the debounced value.
+ * @see https://ahooks.js.org/hooks/use-debounce
+ */
 function useDebounce<T>(value: T, options?: DebounceOptions) {
  const [debounced, setDebounced] = useState(value);
 

packages/hooks/src/useDebounceEffect/index.ts

@@ -4,6 +4,10 @@ import type { DebounceOptions } from '../useDebounce/debounceOptions';
 import useDebounceFn from '../useDebounceFn';
 import useUpdateEffect from '../useUpdateEffect';
 
+/**
+ * Debounce your `useEffect`.
+ * @see https://ahooks.js.org/hooks/use-debounce-effect
+ */
 function useDebounceEffect(
  effect: EffectCallback,
  deps?: DependencyList,

packages/hooks/src/useDebounceFn/index.ts

@@ -8,6 +8,10 @@ import isDev from '../utils/isDev';
 
 type noop = (...args: any[]) => any;
 
+/**
+ * A hook that deal with the debounced function.
+ * @see https://ahooks.js.org/hooks/use-debounce-fn
+ */
 function useDebounceFn<T extends noop>(fn: T, options?: DebounceOptions) {
  if (isDev) {
  if (!isFunction(fn)) {

packages/hooks/src/useDeepCompareEffect/index.tsx

@@ -1,4 +1,8 @@
 import { useEffect } from 'react';
 import { createDeepCompareEffect } from '../createDeepCompareEffect';
 
+/**
+ * Usage is the same as `useEffect`, but deps are compared with [lodash.isEqual](https://lodash.com/docs/4.17.15#isEqual).
+ * @see https://ahooks.js.org/hooks/use-deep-compare-effect
+ */
 export default createDeepCompareEffect(useEffect);

packages/hooks/src/useDeepCompareLayoutEffect/index.tsx

@@ -1,4 +1,8 @@
 import { useLayoutEffect } from 'react';
 import { createDeepCompareEffect } from '../createDeepCompareEffect';
 
+/**
+ * Usage is the same as `useLayoutEffect`, but deps are compared with [lodash.isEqual](https://lodash.com/docs/4.17.15#isEqual).
+ * @see https://ahooks.js.org/hooks/use-deep-compare-layout-effect
+ */
 export default createDeepCompareEffect(useLayoutEffect);

packages/hooks/src/useDocumentVisibility/index.ts

@@ -11,6 +11,10 @@ const getVisibility = () => {
  return document.visibilityState;
 };
 
+/**
+ * A Hook can tell if the page is visible, refer to [visibilityState API](https://developer.mozilla.org/docs/Web/API/Document/visibilityState)
+ * @see https://ahooks.js.org/hooks/use-document-visibility
+ */
 function useDocumentVisibility(): VisibilityState {
  const [documentVisibility, setDocumentVisibility] = useState(() => getVisibility());
 

packages/hooks/src/useDrag/index.ts

@@ -16,6 +16,10 @@ export interface Options {
  };
 }
 
+/**
+ * help you manage data transfer between drag and drop
+ * @see https://ahooks.js.org/hooks/use-drop
+ */
 const useDrag = <T>(data: T, target: BasicTarget, options: Options = {}) => {
  const optionsRef = useLatest(options);
  const dataRef = useLatest(data);

packages/hooks/src/useDrop/index.ts

@@ -16,6 +16,10 @@ export interface Options {
  onPaste?: (event?: React.ClipboardEvent) => void;
 }
 
+/**
+ * help you manage data transfer between drag and drop
+ * @see https://ahooks.js.org/hooks/use-drop
+ */
 const useDrop = (target: BasicTarget, options: Options = {}) => {
  const optionsRef = useLatest(options);
 

packages/hooks/src/useDynamicList/index.ts

@@ -1,5 +1,9 @@
 import { useCallback, useRef, useState } from 'react';
 
+/**
+ * A hook that helps you manage dynamic list and generate unique key for each item.
+ * @see https://ahooks.js.org/hooks/use-dynamic-list
+ */
 const useDynamicList = <T>(initialList: T[] = []) => {
  const counterRef = useRef(-1);
 

packages/hooks/src/useEventEmitter/index.ts

@@ -30,6 +30,10 @@ export class EventEmitter<T> {
  };
 }
 
+/**
+ * Simplifying multiple component passing of parameters
+ * @see https://ahooks.js.org/hooks/use-event-emitter
+ */
 export default function useEventEmitter<T = void>() {
  const ref = useRef<EventEmitter<T>>();
  if (!ref.current) {

packages/hooks/src/useEventListener/index.ts

@@ -14,6 +14,10 @@ type Options<T extends Target = Target> = {
  passive?: boolean;
 };
 
+/**
+ * Use addEventListener elegant by Hook.
+ * @see https://ahooks.js.org/hooks/use-event-listener
+ */
 function useEventListener<K extends keyof HTMLElementEventMap>(
  eventName: K,
  handler: (ev: HTMLElementEventMap[K]) => void,

packages/hooks/src/useEventTarget/index.ts

@@ -13,6 +13,10 @@ export interface Options<T, U> {
  transformer?: (value: U) => T;
 }
 
+/**
+ * A hook that encapsulates `onChange` and `value` logic for form controls that obtains value through `event.target.value`.
+ * @see https://ahooks.js.org/hooks/use-event-target
+ */
 function useEventTarget<T, U = T>(options?: Options<T, U>) {
  const { initialValue, transformer } = options || {};
  const [value, setValue] = useState(initialValue);

packages/hooks/src/useExternal/index.ts

@@ -90,6 +90,10 @@ const loadCss = (path: string, props = {}): loadResult => {
  };
 };
 
+/**
+ * Dynamically load JS or CSS, useExternal can ensure that the resource are globally unique.
+ * @see https://ahooks.js.org/hooks/use-external
+ */
 const useExternal = (path?: string, options?: Options) => {
  const [status, setStatus] = useState<Status>(path ? 'loading' : 'unset');
 

packages/hooks/src/useFavicon/index.ts

@@ -9,6 +9,10 @@ const ImgTypeMap = {
 
 type ImgTypes = keyof typeof ImgTypeMap;
 
+/**
+ * A hook that set the favicon of the page.
+ * @see https://ahooks.js.org/hooks/use-favicon
+ */
 const useFavicon = (href: string) => {
  useEffect(() => {
  if (!href) return;

packages/hooks/src/useFocusWithin/index.tsx

@@ -8,6 +8,10 @@ export interface Options {
  onChange?: (isFocusWithin: boolean) => void;
 }
 
+/**
+ * Monitor whether the current focus is within a certain area, Same as css attribute [:focus-within](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-within).
+ * @see https://ahooks.js.org/hooks/use-focus-within
+ */
 export default function useFocusWithin(target: BasicTarget, options?: Options) {
  const [isFocusWithin, setIsFocusWithin] = useState(false);
  const { onFocus, onBlur, onChange } = options || {};

packages/hooks/src/useFullscreen/index.ts

@@ -17,6 +17,10 @@ export interface Options {
  pageFullscreen?: boolean | PageFullscreenOptions;
 }
 
+/**
+ * manages DOM full screen.
+ * @see https://ahooks.js.org/hooks/use-fullscreen
+ */
 const useFullscreen = (target: BasicTarget, options?: Options) => {
  const { onExit, onEnter, pageFullscreen = false } = options || {};
  const { className = 'ahooks-page-fullscreen', zIndex = 999999 } =

packages/hooks/src/useFusionTable/index.tsx

@@ -3,6 +3,10 @@ import type { Data, Params, Service } from '../useAntdTable/types';
 import { fieldAdapter, resultAdapter } from './fusionAdapter';
 import type { FusionTableOptions, FusionTableResult } from './types';
 
+/**
+ * `useFusionTable` encapsulates the commonly used [Fusion Form](https://fusion.design/pc/component/basic/form) and [Fusion Table](https://fusion.design/pc/component/basic/table) data binding logic.
+ * @see https://ahooks.js.org/hooks/use-fusion-table
+ */
 const useFusionTable = <TData extends Data, TParams extends Params>(
  service: Service<TData, TParams>,
  options: FusionTableOptions<TData, TParams> = {},

packages/hooks/src/useGetState/index.ts

@@ -3,6 +3,10 @@ import { useState, useRef, useCallback } from 'react';
 
 type GetStateAction<S> = () => S;
 
+/**
+ * Add a getter method to the return value of `React.useState` to get the latest value
+ * @see https://ahooks.js.org/hooks/use-get-state
+ */
 function useGetState<S>(
  initialState: S | (() => S),
 ): [S, Dispatch<SetStateAction<S>>, GetStateAction<S>];

packages/hooks/src/useHistoryTravel/index.ts

@@ -31,6 +31,10 @@ const split = <T>(step: number, targetArr: T[]) => {
  };
 };
 
+/**
+ * A hook to manage state change history. It provides encapsulation methods to travel through the history.
+ * @see https://ahooks.js.org/hooks/use-history-travel
+ */
 export default function useHistoryTravel<T>(initialValue?: T, maxLength: number = 0) {
  const [history, setHistory] = useState<IData<T | undefined>>({
  present: initialValue,

packages/hooks/src/useHover/index.ts

@@ -8,6 +8,10 @@ export interface Options {
  onChange?: (isHovering: boolean) => void;
 }
 
+/**
+ * A hook that tracks whether the element is being hovered.
+ * @see https://ahooks.js.org/hooks/use-hover
+ */
 export default (target: BasicTarget, options?: Options): boolean => {
  const { onEnter, onLeave, onChange } = options || {};
 

packages/hooks/src/useInViewport/index.ts

@@ -13,6 +13,10 @@ export interface Options {
  callback?: CallbackType;
 }
 
+/**
+ * Observe whether the element is in the visible area, and the visible area ratio of the element. refer to [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
+ * @see https://ahooks.js.org/hooks/use-in-viewport
+ */
 function useInViewport(target: BasicTarget | BasicTarget[], options?: Options) {
  const { callback, ...option } = options || {};
 

packages/hooks/src/useInfiniteScroll/index.tsx

@@ -7,6 +7,10 @@ import { getTargetElement } from '../utils/domTarget';
 import { getClientHeight, getScrollHeight, getScrollTop } from '../utils/rect';
 import type { Data, InfiniteScrollOptions, Service } from './types';
 
+/**
+ * `useInfiniteScroll` encapsulates the common infinite scroll logic.
+ * @see https://ahooks.js.org/hooks/use-infinite-scroll
+ */
 const useInfiniteScroll = <TData extends Data>(
  service: Service<TData>,
  options: InfiniteScrollOptions<TData> = {},

packages/hooks/src/useInterval/index.ts

@@ -2,6 +2,10 @@ import { useCallback, useEffect, useRef } from 'react';
 import useMemoizedFn from '../useMemoizedFn';
 import { isNumber } from '../utils';
 
+/**
+ * A hook that handles the `setInterval` timer function.
+ * @see https://ahooks.js.org/hooks/use-interval
+ */
 const useInterval = (fn: () => void, delay?: number, options: { immediate?: boolean } = {}) => {
  const timerCallback = useMemoizedFn(fn);
  const timerRef = useRef<NodeJS.Timer | null>(null);

packages/hooks/src/useIsomorphicLayoutEffect/index.ts

@@ -1,6 +1,26 @@
 import { useEffect, useLayoutEffect } from 'react';
 import isBrowser from '../utils/isBrowser';
 
+/**
+ * Return useLayoutEffect for browser environment and useEffect for other environments.
+ * @description
+ * In SSR mode, the following warning will appear when useLayoutEffect is used
+ *
+ * > ⚠️ Warning: useLayoutEffect does nothing on the server, because its effect cannot be encoded into the server renderer's output format. This will lead to a mismatch between the initial, non-hydrated UI and the intended UI. To avoid this, useLayoutEffect should only be used in components that render exclusively on the client. See https://fb.me/react-uselayouteffect-ssr for common fixes.
+ *
+ * To avoid this warning, `useIsomorphicLayoutEffect` can be used instead of useLayoutEffect.
+ *
+ * The source code:
+ *
+ * ```javascript
+ * const useIsomorphicLayoutEffect = isBrowser ? useLayoutEffect : useEffect;
+ * ```
+ *
+ * Return useLayoutEffect for browser environment and useEffect for other environments.
+ *
+ * For more information, please refer to [useLayoutEffect and SSR](https://medium.com/@alexandereardon/uselayouteffect-and-ssr-192986cdcf7a)
+ * @see https://ahooks.js.org/hooks/use-isomorphic-layout-effect
+ */
 const useIsomorphicLayoutEffect = isBrowser ? useLayoutEffect : useEffect;
 
 export default useIsomorphicLayoutEffect;

packages/hooks/src/useKeyPress/index.ts

@@ -220,6 +220,10 @@ function genKeyFormatter(keyFilter: KeyFilter, exactMatch: boolean): KeyPredicat
 
 const defaultEvents: KeyEvent[] = ['keydown'];
 
+/**
+ * Listen for the keyboard press, support key combinations, and support alias.
+ * @see https://ahooks.js.org/hooks/use-key-press
+ */
 function useKeyPress(
  keyFilter: KeyFilter,
  eventHandler: (event: KeyboardEvent, key: KeyType) => void,

packages/hooks/src/useLatest/index.ts

@@ -1,5 +1,9 @@
 import { useRef } from 'react';
 
+/**
+ * A Hook that returns the latest value, effectively avoiding the closure problem.
+ * @see https://ahooks.js.org/hooks/use-latest
+ */
 function useLatest<T>(value: T) {
  const ref = useRef(value);
  ref.current = value;