ReactJS编写无状态函数注释

Posted 2021-04-04

为ReactJS无状态函数编写注释的推荐方法是什么？

假设我有以下代码：

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的参数似乎毫无意义，因为每个反应组件都有props作为参数，而道具键是函数中最重要的部分。

有官方指导方针吗？ （我没找到）

---

EDIT

我也有PropTypes定义：

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

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

答案

您可以在属性名称前指定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>
));

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

另一答案

我知道这个晚会差不多晚了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类型。

另一答案

另一个选择是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没有出现;这是一个非常粗糙的库，但我有同样的问题，找到了这个，并且必须努力清理一些。