如何在React Hooks中复用JSDoc函数定义？

我正在给React自定义Hook编写JSDoc，想找到为Hook返回的函数添加文档的最佳方法。初始代码示例如下：

const useMyHook = () => {
    /**
     * a long and informative description for function 1
     * @param {string} name
     * @returns {void}
     */
    const function1 = (name) => {
        // function does something.
        console.log(name);
    };

    /**
     * a long and informative description for function 2
     * @returns {string}
     */
    const function2 = () => {
        // function does something else
        return 'hello';
    };

    return { function1, function2 };
};

我尝试过通过@typedef定义Hook返回值的方式，但遇到两个明显问题：

• 其他开发者使用Hook时，只能看到typedef里的简短描述，无法获取函数本身的完整文档
• 函数签名需要重复编写两次（typedef里一次、函数上方一次），后续修改要维护两处内容

对应的示例代码：

/**
 * @typedef UseMyHookReturn
 * @property {(name:string) => void} function1 - short description for function 1.
 * @property {() => string} function2 - short description for function 2.
 */

/**
 * This is my hook
 * @returns {UseMyHookReturn}
 */
const useMyHook = () => {
    // 函数定义同上...
};

// 使用者只能看到typedef里的简短描述
const { function1, function2 } = useMyHook();

解决方案：用@callback复用函数定义与文档 #

可以通过@callback先定义函数的完整类型和文档，再在函数实现和Hook返回值中复用这个定义，这样只需维护一处内容：

/**
 * a long and informative description for function 1
 * @callback UseMyHookFunction1
 * @param {string} name - 参数name的详细说明
 * @returns {void}
 */

/**
 * a long and informative description for function 2
 * @callback UseMyHookFunction2
 * @returns {string} - 返回值的详细说明
 */

/**
 * @typedef UseMyHookReturn
 * @property {UseMyHookFunction1} function1 - function1的功能概述（IDE会自动关联@callback里的完整文档）
 * @property {UseMyHookFunction2} function2 - function2的功能概述
 */

/**
 * This is my hook
 * @returns {UseMyHookReturn}
 */
const useMyHook = () => {
    // 用@type引用已定义的callback类型，无需重复写JSDoc
    const function1 = /** @type {UseMyHookFunction1} */ (name) => {
        console.log(name);
    };

    const function2 = /** @type {UseMyHookFunction2} */ () => {
        return 'hello';
    };

    return { function1, function2 };
};

这种方式的优势：

• 只需在@callback中编写一次完整的函数文档和签名，后续修改仅需维护这一处
• 其他开发者使用Hook时，IDE会自动显示@callback里的完整描述，包括参数、返回值的详细说明
• 避免重复代码，降低维护成本

如果不想额外定义@typedef，也可以直接在Hook的@returns中使用@callback类型：

/**
 * a long and informative description for function 1
 * @callback UseMyHookFunction1
 * @param {string} name
 * @returns {void}
 */

/**
 * a long and informative description for function 2
 * @callback UseMyHookFunction2
 * @returns {string}
 */

/**
 * This is my hook
 * @returns {{
 *   function1: UseMyHookFunction1,
 *   function2: UseMyHookFunction2
 * }}
 */
const useMyHook = () => {
    const function1 = /** @type {UseMyHookFunction1} */ (name) => {
        console.log(name);
    };

    const function2 = /** @type {UseMyHookFunction2} */ () => {
        return 'hello';
    };

    return { function1, function2 };
};

内容的提问来源于stack exchange，提问作者Ori Swid