如何为TypeScript函数的泛型类型参数编写JSDoc文档？

正确标签：@template #

要给泛型类型参数添加可正常显示的JSDoc文档，应该使用@template标签而非@param。@param是专门用于标记函数入参的，泛型类型参数有专属的@template标签，VS Code等主流编辑器对该标签的悬停提示支持完善。

示例代码：

/**
 * 处理输入数组并返回处理后的结果
 * @template T - 数组元素的类型，可指定任意合法TypeScript类型
 * @param {T[]} arr - 需要处理的目标数组
 * @returns {T[]} 处理完成后的数组
 */
function processArray<T>(arr: T[]): T[] {
  // 你的处理逻辑
  return arr.map(item => item);
}

此时鼠标悬停在函数定义里的T上，就能看到你编写的泛型参数说明。

关于@param T的实践建议 #

如果遇到旧版本TypeScript或编辑器不支持@template提示的情况，用@param T虽能留下注释，但并不符合JSDoc规范——它会混淆“泛型类型参数”和“函数入参”的概念，还可能在其他工具或新环境下出现解析问题。

因此更推荐坚持使用标准的@template标签，这是TypeScript官方认可的泛型参数文档写法，能保证在主流开发工具里的一致性表现。

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