ReactJS 编写无状态函数注释

Question

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

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

编辑

我也PropTypes定义了：

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

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

Answer 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>
));

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

Answer 2

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

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

这会为 class 创建一个 "Properties" 文档部分，其中包含您所期望的内容，大致如下：

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

我不确定为什么 Type 没有出现；这是一个非常简陋的图书馆，但我有同样的问题，找到了这个，并且必须努力清理它。

Answer 3

我知道我迟到了将近 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。

Answer 4

我想你可以用这个：

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

并且 return 类型中的 void 可以替换为数字或字符串等任何数据类型。

ReactJS 编写无状态函数注释

ReactJS writing stateless function comments

javascript

reactjs

code-documentation

编辑