如何在React/TypeScript组件中让Props注释显示在组件文档中？

一、主流IDE插件支持 #

• TypeScript Hero：可自动提取Props类型的JSDoc注释，在hover组件时展示完整的Props信息，还能快速生成Props注释模板，减少重复编写工作。
• DocFX for TypeScript：虽主打静态文档生成，但在IDE内可关联Props类型注释，hover组件时会同步显示Props的注释内容，适配代码与文档同步维护的场景。
• ESLint + eslint-plugin-jsdoc：配合require-param-description、require-property-description规则，可强制Props类型注释的完整性，部分工具能基于这些注释生成组件文档，确保代码注释与文档一致。

二、替代JSDoc的更完善方案 #

1. TypeDoc + React插件 #

TypeDoc原生支持解析TypeScript类型注释，搭配typedoc-plugin-react插件，可自动提取React组件的Props类型注释并生成静态文档，完全复用代码中的类型注释，无需重复编写。

示例配置（typedoc.json）：

{
  "plugins": ["typedoc-plugin-react"],
  "entryPoints": ["./src/components/Table.tsx"],
  "out": "./docs"
}

2. Storybook + TypeDoc集成 #

若使用Storybook编写组件文档，通过storybook-addon-docs插件集成TypeDoc后，会自动解析组件的Props类型注释，在Storybook文档面板展示组件描述、所有Props的类型、默认值及注释。代码注释修改后，文档会实时更新，彻底避免注释过时问题。

Storybook配置示例（.storybook/main.js）：

module.exports = {
  addons: ['@storybook/addon-docs'],
};

组件代码示例：

/**
 * A table component
 */
export const Table = ({ columns, rows }: TableProps) => {
  // 组件逻辑
};

/**
 * 表格列配置
 */
type TableProps = {
  /**
   * 列定义数组，包含列标题、数据字段等信息
   */
  columns: Column[];
  /**
   * 表格数据源数组
   */
  rows: Record<string, any>[];
};

3. 自定义TS类型解析脚本 #

若需定制化文档格式，可借助typescript包的API编写解析脚本，读取组件文件的AST，提取组件和Props的注释，生成MDX、Markdown等格式的文档。这种方式完全可控，适配有特殊文档规范的项目。

核心思路示例：

import * as ts from 'typescript';
import fs from 'fs';

// 读取组件文件
const sourceFile = ts.createSourceFile(
  './src/components/Table.tsx',
  fs.readFileSync('./src/components/Table.tsx', 'utf8'),
  ts.ScriptTarget.Latest,
  true
);

// 遍历AST，查找ExportDeclaration（组件）和TypeAliasDeclaration（Props类型）节点，提取JSDoc注释

三、关键注意事项 #

• 确保Props类型的注释使用标准/** ... */格式，便于工具解析。
• 避免在组件注释中重复编写Props说明，直接复用类型注释，降低维护成本。
• 优先选择与现有开发流程集成的方案（如已用Storybook则集成addon-docs），减少额外学习成本。

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