JSDoc Tag Support for React HOC (Higher-Order Component)

Question

What is the proper way to document a React Higher-Order Component using JSDoc? There aren't, of course, any React-specific tags built-in - so what would be the proper approach?

Answer 1

To document a high-order component with JSDoc, you would follow the standard as laid out below. To clarify, the documentation is usually found where the higher-order component is defined and not necessarily where it's used. If you want to document where it's used, that can be documented in that component's JSDocs as a @description, @see, @link, or other relevant tags.

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

Documentation with React, and code in general, is always interesting. There are several ways and along with it, advantages and disadvantages of each. Ask yourself what it's going to be used for? Creating a documentation website, sharing between teammates, developers only, etc.? That being said, the most common ways to purely document are JSDoc and Markdown.

• Markdown (e.g., Material UI)
• MarkdownX (MDX

There are other ways to visualize components that have built-in documentation functionality usually based around Markdown or JSDoc as well. This becomes extremely useful when working within a team or publishing packages.

• Bit (Bit Documentation)
• Storybook (Storybook for MD)
• React StyleGuidist (StyleGuidist Docs)