React 和 JSDoc - 如何正确记录 React 组件？

Question

我正在记录我的React Native组件，但我不知道如何正确执行。

对于文档生成，我使用jsdoc/better-docs，据说它能够收集您留下的评论PropTypes并将其包含在文档中。但是...由于不兼容问题，不可能在 React Native 中执行此策略，因此，它们PropTypes 不包含在文档中。

如何使用 JSDOC 记录此 React 组件？

/**
 * ??
 */
function Cat({ name, color = "#000" }) {
  return <View />;
}

Cat.propTypes = {
  name: PropTypes.string.isRequired,
  color: PropTypes.string,
};

---

我正在做以下事情：

/**
 * The cat properties.
 *
 * @typedef {object} Props
 * @property {string} name - The cat name.
 * @property {string} [color="#000"] - The cat color.
 */

/**
 * Cat component.
 *
 * @type {React.FC<Props>}
 * @returns {React.ReactElement} The cat.
 */
function Cat({ name, color = "#000" }) {
  return <View />;
}

Cat.propTypes = {
  /** The cat name. */
  name: PropTypes.string.isRequired,

  /** The cat color. */
  color: PropTypes.string,
};

但我觉得添加类型定义后 prop-types 就没用了（？）。

你如何记录你的反应组件？

Answer 1

方法是使用InferPropsfromprop-types。此方法仅适用于 TypeScript :( 并且我没有使用它...相反，我在我的项目中结合了 JSDoc 和 PropTypes，以在开发体验中获得一些“打字稿行为”并自动生成我的文档。

\n

但有一个无需 Typescript 的解决方法

\n

只需按照我在此处描述的方式配置 JSDoc：JSDoc - 重用类型定义错误（找不到名称 \xe2\x80\x98type name\xe2\x80\x99）

\n

现在，在您的代码中，只需执行以下操作：

\n

组件/cat/propTypes.js：

\n

...\n\nexport const CatPropTypes = {\n   /** The cat data. */\n   data: CatDataShape,\n   /** The cat name. */\n   name: PropTypes.string.isRequired,\n   /** The cat color. */\n   color: PropTypes.string,\n};\n

\n

组件/cat/Cat.js：

\n

import React from "react";\nimport { View } from "react-native";\nimport { InferProps } from "prop-types";\n\nimport { CatPropTypes } from "./propTypes"; // <-----\n\n/**\n * Cat component.\n *\n * @type {React.FC<InferProps<import("./propTypes").CatPropTypes>>} <---- JSDoc is in TypeScript mode! FANTASTIC! :D\n * @returns {React.ReactElement} The cat.\n */\nfunction Cat({ name, color = "#000" }) {\n  return <View />;\n}\n\nCat.propTypes = CatPropTypes; // <-----\n

\n

现在一切都很顺利，没有理由维护无用的 JSDoc typedef！:DDDDDD

\n