TypeDoc中函数注释位置疑问：为何函数comment属性为空？

算力阿峰

2026-7-18

TypeDoc函数注释找不到？看这几个方向

在TypeDoc 0.24.7 + TypeScript 5.0.4的场景下，你遇到的函数声明comment为undefined但注释能正常显示的问题，本质是注释没有挂载在你当前获取的顶层函数节点上，而是存在于其他关联节点中，以下是具体排查和解决方向：

1. 查看函数的`signatures`数组

TypeDoc中函数的注释默认关联到它的签名对象，而非顶层函数声明。你可以遍历函数对象的signatures数组，从中获取comment：

// 在converter事件回调中处理函数节点
if (declaration.kind === 64) { // 64对应Function类型
  const targetSignature = declaration.signatures?.find(s => s.comment);
  if (targetSignature) {
    // 这里可以修改comment.summary
    targetSignature.comment.summary = /* 你的修改内容 */;
  }
}

2. 检查声明的来源与转换标记

从你的示例来看，函数来自.d.ts文件且conversionFlags为0，而有注释的CellSetTable的conversionFlags为1。conversionFlags:0意味着这个节点是外部引用声明，注释可能存储在原始.ts源文件的对应节点中，而非d.ts生成的声明节点里。你可以：

确认函数的原始.ts文件是否存在完整注释
检查TypeDoc配置中是否正确包含了原始源文件的解析范围

3. 切换到`EVENT_RESOLVE_DECLARATION`事件

converter.EVENT_CREATE_DECLARATION是节点创建初期触发的事件，此时注释可能还未完成关联。改用converter.EVENT_RESOLVE_DECLARATION事件，这个阶段节点已完成解析，注释会正确挂载到对应位置：

converter.on(converter.EVENT_RESOLVE_DECLARATION, (context, declaration) => {
  if (declaration.kind === 64 && declaration.comment) {
    // 此时大概率能拿到comment
  }
});