TypeDoc生成React TS文档时忽略顶层注释问题如何解决

核心原因 #

• TypeDoc 对文件级注释的解析规则是：仅识别所有 import/export 语句之前的顶层JSDoc，import、export语句之后写的顶层注释不会被关联到任何模块或导出实体，直接被忽略。
• index.ts里用的export * from "./LogoSafe"属于匿名转发导出，TypeDoc默认会直接追溯到源文件LogoSafe.tsx的组件定义作为导出项，不会绑定index.ts里写在转发语句旁的注释。
• 注释写法存在错误：模块级注释里使用@param是无效的，@param仅能用于描述函数、类方法的参数；重复声明@module标签也会导致注释解析逻辑异常。
• typedoc.json存在配置错误：TypeDoc会自动读取项目根目录的tsconfig.json编译配置，不需要重复声明compilerOptions，且配置项里的tsx: "react"是无效字段，正确字段为jsx。

具体修复步骤 #

1. 调整index.ts的导出和注释写法 #

不要用匿名的export *转发，改为显式命名导出，注释直接绑定到导出语句上，且所有文件级注释必须放在所有导入、导出语句之前：

// 所有注释必须放在文件最顶部，import/export语句之前
/**
 * Logo安全展示组件模块
 * 提供适配不同尺寸、主题的品牌Logo渲染能力
 */
import type { FC } from 'react';

/**
 * 品牌Logo安全渲染组件
 * @param classNameCustom - 自定义样式类名
 * @param isSmall - 是否使用小尺寸模式渲染
 */
export { default as LogoSafeComponent } from "./LogoSafe";

2. 修正typedoc.json配置 #

移除重复无效的compilerOptions配置，补充必要的解析规则：

{
  "entryPoints": ["src/components/LogoSafe/index.ts"],
  "out": "type-doc",
  "excludePrivate": true,
  "plugin": ["typedoc-plugin-markdown"],
  "excludeNotDocumented": false
}

3. 组件源文件补充标准JSDoc #

直接在LogoSafe.tsx的组件定义处写注释，这部分注释是编辑器悬停、TypeDoc解析优先级最高的内容，示例：

/**
 * 品牌Logo安全渲染组件
 * 自动处理明暗主题适配、加载失败兜底逻辑
 * @param classNameCustom - 自定义挂载的样式类名
 * @param isSmall - 是否渲染小尺寸版本，默认值为false
 */
const LogoSafeComponent: FC<LogoSafeProps> = ({
  classNameCustom,
  isSmall = false
}) => {
  // 组件实现逻辑
}

export default LogoSafeComponent;

4. 重新生成文档 #

执行TypeDoc生成命令后，即可实现编辑器悬停提示、生成的html/md文档展示内容完全一致，所有注释、参数说明、类型定义都能正常渲染，不会出现注释丢失的问题。

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