jmarceli jmarceli - 4 months ago 14
Javascript Question

ReactJS writing stateless function comments

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?

Answer

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.

Comments