使用解构赋值时如何正确为React组件的Props编写JSDoc

针对你遇到的解构Props组件JSDoc文档问题，以下两种是业界常用的最优解决方案：

方案一：接口注释+组件JSDoc关联接口 #

这是最符合TypeScript规范的写法，既能维护类型定义的完整性，又能让组件文档自动关联字段注释。

实现步骤： #

1. 为IPostComponent接口的每个字段添加JSDoc注释
2. 在组件的JSDoc中用@param标注整体props参数，并关联接口类型

/**
 * 文章展示组件
 * @param {IPostComponent} props - 组件的配置参数
 */
interface IPostComponent {
  /** 文章标题，用于展示文章的主标题 */
  title: string;
  /** 文章正文内容，支持纯文本或简单HTML */
  body: string;
}

const PostComponent: React.FC<IPostComponent> = ({ title, body }) => {
  return (
    <div>
      <h1>{title}</h1>
      <p>{body}</p>
    </div>
  );
};

效果：悬停组件时，VS Code会显示props的整体说明，点击展开后能看到每个字段的详细注释；单独悬停title或body时也能看到对应注释，完全满足文档需求，且不会出现警告。

方案二：直接在组件JSDoc中标注解构参数 #

如果需要在组件文档中直接列出每个参数，可使用JSDoc的对象解构参数语法，同时处理VS Code的警告。

/**
 * 文章展示组件
 * @param {string} props.title - 文章标题，用于展示文章的主标题
 * @param {string} props.body - 文章正文内容，支持纯文本或简单HTML
 */
// @ts-ignore 忽略JSDoc与函数签名不匹配的警告
interface IPostComponent {
  title: string;
  body: string;
}

const PostComponent: React.FC<IPostComponent> = ({ title, body }) => {
  return (
    <div>
      <h1>{title}</h1>
      <p>{body}</p>
    </div>
  );
};

说明：这种写法会让组件文档直接展示两个参数，但VS Code会因JSDoc参数与函数签名（仅一个props参数）不匹配而弹出警告，可通过// @ts-ignore忽略，或调整VS Code的TypeScript设置关闭相关提示。不过方案一更推荐，因为它更贴合TypeScript的类型系统设计。

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