React HOC（高阶组件）的 JSDoc 标签支持答案

【问题标题】：JSDoc Tag Support for React HOC (Higher-Order Component)React HOC（高阶组件）的 JSDoc 标签支持
【发布时间】：2017-10-04 14:58:08
【问题描述】：

使用JSDoc 记录React Higher-Order Component 的正确方法是什么？当然，没有任何 React-specific tags 内置 - 那么正确的方法是什么？

【问题讨论】：

嗯，使用 React，您可以通过自省提取大量信息。除非 JsDoc 是严格要求，否则你可以使用 react-styleguidist 或 react-docgen 或 bluekit 之类的东西做得更好。
side-comment：VS-Code 中的“JSDoc”不像 100% JSDoc，因为您实际上是在 JSDoc 标签内编写打字稿语法而不是“vanilla”JSDoc。
TypeScript，在很多方面都比 JSDoc 好很多，并且正在上升

标签： reactjs jsdoc3

【解决方案1】：

要使用 JSDoc 记录高阶组件，您需要遵循以下标准。为了澄清，文档通常在定义高阶组件的地方找到，而不一定在使用它的地方。如果您想记录它的使用位置，可以在该组件的 JSDocs 中记录为 @description、@see、@link 或其他相关标签。

  import React, { useState } from 'react';
  import Async from 'react-async';
  import { withTheme } from 'design'; // Contains the JSDoc for this HOC.
  import { getName } from 'api';

  /**
    * Component to render a greeting to someone!
    * 
    * @component
    * @param {string} userId The ID of the user to greet
    */
  export function Hello({ theme, userId }) {
    return (
      <Async promiseFn={getName} userId={userId}>
        <Async.Fulfilled>
          {(data) => <p>Hello {data.name}!</p>}
        </Async.Fulfilled>
      </Async>
    );
  };

  export default withTheme(Hello);

React 文档和一般代码总是很有趣。有几种方法，以及每种方法的优点和缺点。问问自己它会被用来做什么？创建一个文档网站，在队友之间共享，仅限开发人员，等等？话虽如此，纯粹文档的最常用方法是 JSDoc 和 Markdown。

Markdown（例如，Material UI）
MarkdownX (MDX

还有其他方法可以可视化具有内置文档功能的组件，这些功能通常也基于 Markdown 或 JSDoc。这在团队合作或发布包时非常有用。

比特 (Bit Documentation)
故事书 (Storybook for MD)
React StyleGuidist (StyleGuidist Docs)

【讨论】：

【解决方案2】：

在 React 中构建 UI 时，HOC 模式是一个非常重要的代码重用工具。 Prop 类型有助于在 bug 进入生产环境之前发现它们。

但是，编写能够正确处理它们包装的组件的 prop 类型的 HOC 是困难的，并且需要大量的样板代码。理想情况下，工程师不应回避将逻辑转移到 HOC，因为它太冗长而无法编写。

为了解决这个问题，react-create-hoc 提供了一个函数来实现这个样板的大部分内容。它允许仅使用简单的函数来创建 HOC，该函数只是将组件包装在新组件中。

用法

import React from 'react';
import PropTypes from 'prop-types';
import createHOC from 'react-create-hoc';

function WelcomeMessage({ name }) {
  return <div>{greeting}, {name}!</div>;
}

WelcomeMessage.propTypes = {
  greeting: PropTypes.string.isRequired,
  name: PropTypes.string.isRequired,
};

const withModifiedName = createHOC(
  'withModifiedName',
  (ComponentToWrap, nameModifier) => {
    function WithModifiedName({ nameProvider, ...rest }) {
      return (
        <ComponentToWrap
          name={nameModifier(nameProvider())}
          {...rest}
        />
      );
    }

    WithModifiedName.propTypes = {
      nameProvider: PropTypes.func.isRequired,
    };

    return WithModifiedName;
  },
  {
    factory: true,
    passedProps: ['name'],
  },
);

// WrappedWelcomeMessage has the following prop types:
// {
//   greeting: PropTypes.string.isRequired,
//   nameProvider: PropTypes.func.isRequired,
// }
const WrappedWelcomeMessage = withModifiedName(
  // nameModifier param
  name => name.toUpperCase(),
)(WelcomeMessage);

// Renders a div containing, "Rise and shine, MR. FREEMAN!"
ReactDOM.render(
  <WrappedWelcomeMessage
    greeting="Rise and shine"
    nameProvider={() => 'Mr. Freeman'}
  />,
  document.getElementById('root'),
);

【讨论】：