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

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

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

只需按照我在此处描述的方式配置您的 JSDoc：JSDoc - 重用类型定义错误（找不到名称“类型名称” )

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

components/cat/propTypes.js：

...

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

components/cat/Cat.js：

import React from "react";
import { View } from "react-native";
import { InferProps } from "prop-types";

import { CatPropTypes } from "./propTypes"; // <-----

/**
 * Cat component.
 *
 * @type {React.FC<InferProps<import("./propTypes").CatPropTypes>>} <---- JSDoc is in TypeScript mode! FANTASTIC! :D
 * @returns {React.ReactElement} The cat.
 */
function Cat({ name, color = "#000" }) {
  return <View />;
}

Cat.propTypes = CatPropTypes; // <-----

现在一切正常就像一个魅力，没有理由维护无用的 JSDoc typedef：DDDDDD！