ReactJS 写无状态函数注释答案

【问题标题】：ReactJS writing stateless function commentsReactJS 写无状态函数注释
【发布时间】：2016-12-07 15:38:21
【问题描述】：

为 ReactJS 无状态函数编写 cmets 的推荐方式是什么？

假设我有以下代码：

export const LoginForm = ({ submitting, handleSubmit }) => (
  <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
));

文档注释应该是什么样子？

我的第一个想法是：

/**
 * Form for user login
 * @param {bool} submitting Shows if form submitting is in progress
 * @param {function} handleSubmit Form submit callback function
 */

但这不正确，因为submitting 和handleSubmit 不是LoginForm 函数的真正参数。它们只是 props 参数的键。另一方面，将props 记录为LoginForm 的参数似乎毫无意义，因为每个react 组件都有props 作为参数，并且props 键是函数中最重要的部分。

是否有任何官方指南？（没找到）

编辑

我也定义了PropTypes：

LoginForm.propTypes = {
  submitting: PropTypes.bool,
  handleSubmit: PropTypes.func.isRequired,
};

也许这是道具相关文档的地方？如果是这样，它应该是什么样子？有什么标准吗？

【问题讨论】：

我认为 PropTypes 会更受欢迎.. 但不确定
是的，我当然定义了 PropTypes，但这不是真正的文档，因为没有提供描述，只有属性类型。也许我应该记录 PropTypes？如果是这样，这应该是什么样子。

标签： javascript reactjs code-documentation

【解决方案1】：

你可以在属性名前指定props对象：

/**
 * Form for user login
 * @param {object} props Component props
 * @param {bool} props.submitting Shows if form submitting is in progress
 * @param {function} props.handleSubmit Form submit callback function
 */
export const LoginForm = ({ submitting, handleSubmit }) => (
  <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
));

有关更多信息，请参阅Parameters With Properties 部分中的@param wiki 页面。

【讨论】：

@return 类型呢？
你可以添加类似@returns {JSX.Element} Component template

【解决方案2】：

我知道我迟到了将近 3 年参加这个聚会。只是添加以供参考。可以这样做：

/**
 * @typedef {Object<string, any>} Props
 * @property {boolean} submitting Shows if form submitting is in progress
 * @property {function} handleSubmit Form submit callback function
 */

/** 
 * Form for user login
 *
 * @type {import('react').FunctionComponentElement<Props>}
 */
export const LoginForm = ({ submitting, handleSubmit }) => (
    <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
);

为简洁起见，也可以这样做：

/**
 * Form for user login
 *
 * @type {import('react').FunctionComponentElement<{
       submitting: boolean,
       handleSubmit: function
    }>}
 */
export const LoginForm = ({ submitting, handleSubmit }) => (
    <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
);

如果在您的 IDE 中启用了 Typescript，您可以避免在此设置中完全声明 prop-types。

【讨论】：

【解决方案3】：

另一个选项是jsdoc-react-proptypes，这样使用：

SomeComponent.propTypes = {
  /** Function to run after animation completes. */
  onStop: PropTypes.func
};

这会为该类创建一个“属性”文档部分，其中包含您所期望的大致内容：

Name    Type Attributes  Description
onStop       <optional>  Function to run after animation completes.

我不知道为什么Type 没有出现；这是一个相当粗糙的库，但我有同样的问题，发现了这个，并且必须努力清理它。

【讨论】：

【解决方案4】：

我认为你可以使用这个：

 * @property {function(argType1, argType2, argTypeN): void} handleSubmit - The handleSubmit Form submit callback function

并且返回类型中的 void 可以替换为任何数据类型，如数字或字符串。

【讨论】：