What is the recommended way of writing comments for ReactJS stateless functions?

Let say I have the following code:

export const LoginForm = ({ submitting, handleSubmit }) => (
  <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
));

How should documentation comment look like?

My first idea was:

/**
 * Form for user login
 * @param {bool} submitting Shows if form submitting is in progress
 * @param {function} handleSubmit Form submit callback function
 */

But this is not correct as submitting and handleSubmit are not real params of the LoginForm function. They are just keys of the props parameter. On the other hand documenting props as the parameter of LoginForm seems to be pointless because every react component has props as a parameter and the props keys are most important part of the function.

Are there any official guidelines? (I didn't find any)

EDIT

I have also PropTypes defined:

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

Maybe this is the place for props related documentation? If so how should it look like? Is there any standard for that?

What is the recommended way of writing comments for ReactJS stateless functions?

Let say I have the following code:

export const LoginForm = ({ submitting, handleSubmit }) => (
  <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
));

How should documentation comment look like?

My first idea was:

/**
 * Form for user login
 * @param {bool} submitting Shows if form submitting is in progress
 * @param {function} handleSubmit Form submit callback function
 */

But this is not correct as submitting and handleSubmit are not real params of the LoginForm function. They are just keys of the props parameter. On the other hand documenting props as the parameter of LoginForm seems to be pointless because every react component has props as a parameter and the props keys are most important part of the function.

Are there any official guidelines? (I didn't find any)

EDIT

I have also PropTypes defined:

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

Maybe this is the place for props related documentation? If so how should it look like? Is there any standard for that?

• javascript
• reactjs
• code-documentation

• I think that PropTypes would be perfered.. but not sure – TryingToImprove Commented Aug 2, 2016 at 10:26
• Yeah of course I have PropTypes defined but this is not real documentation as there is no description provided, only property type. Maybe I should document PropTypes? If so how this should look like. – jmarceli Commented Aug 2, 2016 at 10:43

5 Answers 5

You can specify props object before property name:

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

For more info see @param wiki page in Parameters With Properties section.

I know I am almost 3 years late to this party. Just adding for reference. One could do this:

/**
 * @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>
);

For brevity, one could also do:

/**
 * Form for user login
 *
 * @type {import('react').FunctionComponentElement<{
       submitting: boolean,
       handleSubmit: function
    }>}
 */
export const LoginForm = ({ submitting, handleSubmit }) => (
    <form onSubmit={handleSubmit(submit)}> ...(code)... </form>
);

If Typescript is enabled in your IDE, you could avoid declaring prop-types altogether with this setup.

Another option is jsdoc-react-proptypes, used like this:

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

This creates a "Properties" documentation section for the class that includes what you'd expect, roughly:

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

I'm not sure why the Type doesn't show up; it's a pretty rough-shod library, but I had the same question, found this, and will have to work on cleaning it up some.

I think you can use this:

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

And void in return type can be replaced by any data type like number or string.

Defining an interface for each of my functional components and doing the documentation on that worked for me. For example:

interface IHeaderButtons {
    /**
     * IRI of the item that the header buttons are for
     */
    iri: string
}

/**
 * Display the Search and "View in STEADY" buttons for a term/class/etc.
 * @returns {React.FC<IHeaderButtons>} React Functional Component
 */
const HeaderButtons: React.FC<IHeaderButtons> = ({iri}) => {
    // ...
}

Visual Studio Code at least is able to generate intellisense based on this: