如何用JSDoc记录从函数返回值解构出的函数集合？

由于无法修改第三方库的createFunctions，可以通过以下几种方式让VSCode识别动态生成函数的文档注释：

方法1：重新包装函数并添加注释 #

将动态生成的函数重新赋值给带有JSDoc注释的变量，编辑器能直接识别这类注释：

import createFunctions from 'some-library'

// 先获取原始动态函数
const [rawFuncA, rawFuncB] = createFunctions('a', 'b');

/**
 * functionA 的详细功能描述
 * @param {string} inputA 传入的字符串参数说明
 * @returns {number} 返回数值类型的结果说明
 */
export const functionA = rawFuncA;

/**
 * functionB 的详细功能描述
 * @param {boolean} inputB 传入的布尔值参数说明
 * @returns {string} 返回字符串类型的结果说明
 */
export const functionB = rawFuncB;

方法2：用JSDoc类型声明绑定注释 #

不需要重新包装函数，通过@typedef定义函数类型并添加注释，再用@type绑定到解构后的变量上：

import createFunctions from 'some-library'

/**
 * @typedef {Function} FunctionA
 * @description functionA 的功能描述
 * @param {string} inputA 参数说明
 * @returns {number} 返回值说明
 */

/**
 * @typedef {Function} FunctionB
 * @description functionB 的功能描述
 * @param {boolean} inputB 参数说明
 * @returns {string} 返回值说明
 */

/**
 * @type {[FunctionA, FunctionB]}
 */
const [functionA, functionB] = createFunctions('a', 'b');

export { functionA, functionB };

方法3：创建类型声明文件（适用于TS或JS项目） #

如果需要全局生效，可在项目中添加针对第三方库的类型声明文件：

// some-library.d.ts
declare module 'some-library' {
  export default function createFunctions(
    nameA: string,
    nameB: string
  ): [
    /** functionA 的功能描述 */
    (inputA: string) => number,
    /** functionB 的功能描述 */
    (inputB: boolean) => string
  ];
}

以上三种方式都能让VSCode正确识别动态生成函数的文档注释，解决直接注释变量或导出语句无效的问题。

内容的提问来源于stack exchange，提问作者Cam Jackson