使用解构赋值时如何正确记录 React 组件的 Props 参数

Question

我正在尝试为使用解构分配来获取道具的 React 组件编写 JSDocs，如下所示。

const PostComponent: React.FC<IPostComponent> = ({ title, body }) => { ... }

我遇到的问题是 JSDocs 期望有一个@param因为 PostComponent 只接受一个组件，但我想记录title和body作为组件的参数。

如果我尝试将它们作为参数包含在内，VScode 会按预期显示警告：

/**
 * @component
 * @param {string} title the title of the post
 * @param {string} body the body of the post
 */
const PostComponent: React.FC<IPostComponent> = ({ title, body }) => { ... }

如果我在IPostComponent接口中记录每个参数，将鼠标悬停在字段上时会显示文档，但它不包含在组件文档中

interface eIPostComponent {
  /** The title of the post */
  title: string;
  /** The body of the post */
  body: string;
}

为该组件包含 JSDocs 的首选方法是什么？

Answer 1

使用 JSDocs，我们可以为我们的代码片段（函数、组件、对象、方法等）编写生动的描述，并且 Typescript 接口和类型提供了我们的代码需要遵循的保护框架，这样我们就不会遇到莫名其妙的类型转换错误。

我通常不会记录接口和类型，而是给它们描述性名称，并在 README.md 文件（例如）中提到将使用该特定接口的位置。

如果我再深入一点 go，我只会在接口定义之前写一个简短的描述注释。 我认为这是一种干净的方式。

Answer 2

您的 function 仅接受一个参数 - object。
您可以在文档中引用它时记录它：

/**
 * @component
 * @param {obj} wrapping object
 * @param {string} obj.title title the title of the post
 * @param {string} obj.body the body of the post
 */
const PostComponent: React.FC<IPostComponent> = ({ title, body }) => { ... }