React and JSDoc - How to document a React component properly?

Question

I am documenting my React Native components, but I don't know how to do it properly.

For the documentation generation, I am using jsdoc/better-docs, which is supposedly able to collect the comments you leave on your PropTypes and include them in the documentation. But... due to incompatibility issues, it is not possible to carry out this strategy in React Native, and, therefore, the PropTypes are not included in the documentation.

How do you document this React component using JSDOC?

/**
 * ??
 */
function Cat({ name, color = "#000" }) {
  return <View />;
}

Cat.propTypes = {
  name: PropTypes.string.isRequired,
  color: PropTypes.string,
};

I was doing the following:

/**
 * The cat properties.
 *
 * @typedef {object} Props
 * @property {string} name - The cat name.
 * @property {string} [color="#000"] - The cat color.
 */

/**
 * Cat component.
 *
 * @type {React.FC<Props>}
 * @returns {React.ReactElement} The cat.
 */
function Cat({ name, color = "#000" }) {
  return <View />;
}

Cat.propTypes = {
  /** The cat name. */
  name: PropTypes.string.isRequired,

  /** The cat color. */
  color: PropTypes.string,
};

But I am feeling that prop-types is useless after adding the type definitions (?).

How do you document your react components?

Also, if I use a complete type definition in the JSDoc, and (for the same component) a simple PropTypes.object in the component.propTypes, I get multiple annoying linter warnings, something that makes me doubt about the parallel use of jsdoc and proptypes. — Victor Molina
– Victor Molina, Commented Feb 22, 2022 at 15:27

Victor Molina · Accepted Answer · 2022-02-22 21:55:00Z

8

The way to go is to use InferProps from prop-types. This method is only available for TypeScript :( and I am not using it... instead, I am combining JSDoc and PropTypes in my project to get some "typescript behaviors" in the development experience and auto-generate my documentation.

BUT THERE IS A WORKAROUND WITHOUT TYPESCRIPT

Just configure your JSDoc as I described here: JSDoc - reusing type definitions error (cannot find name ‘type name’)

Now, in your code, just do the following:

components/cat/propTypes.js:

...

export const CatPropTypes = {
   /** The cat data. */
   data: CatDataShape,
   /** The cat name. */
   name: PropTypes.string.isRequired,
   /** The cat color. */
   color: PropTypes.string,
};

components/cat/Cat.js:

import React from "react";
import { View } from "react-native";
import { InferProps } from "prop-types";

import { CatPropTypes } from "./propTypes"; // <-----

/**
 * Cat component.
 *
 * @type {React.FC<InferProps<import("./propTypes").CatPropTypes>>} <---- JSDoc is in TypeScript mode! FANTASTIC! :D
 * @returns {React.ReactElement} The cat.
 */
function Cat({ name, color = "#000" }) {
  return <View />;
}

Cat.propTypes = CatPropTypes; // <-----

Now everything is working like a charm and there is no reason to maintain useless JSDoc typedefs! :DDDDDD

edited Feb 22, 2022 at 21:55

answered Feb 22, 2022 at 19:58

Victor Molina

2,6813 gold badges29 silver badges61 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

MiB Feb 21 at 15:42

If your using React 19. note that "PropTypes were deprecated in April 2017 (v15.5.0). In React 19, we’re removing the propType checks from the React package, and using them will be silently ignored.", from Removed deprecated React APIs

Collectives™ on Stack Overflow

React and JSDoc - How to document a React component properly?

1 Answer 1

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related