React: Documenting like a pro

You've made you first ReactJS component it works and it's beautiful, well done you. You know exactly how it works, for now, but when you comeback to the component in 6 months or pass it on to a co-worker for some project things may go awry, what does this function do? What properties can I pass in? Etc.

Let's go over documenting your JS files so you can remember, or learn, how to use a component at a glance. This is the component we'll be documenting, a very simple Hello World! that shows how states can be used.

General Component

When documenting the component it's good to outline what a component does and also give a simple example of how the component can be used.

You can also include some information such as the version number and who you are, as the developer.

/**
 * a very simple `Hello World!` component 
 * showing how states can be used.
 *
 * @version 0.0.1
 * @author [Andrew Bone](https://github.com/link2twenty)
 *
 * @example 
 * <HelloWorld defaultText="World!" />
 * <HelloWorld defaultText="there! General Kenobi?" locked />
 *
 */
export default class HelloWorld extends React.Component {
  // ...
}

Functions

We only have one function in this component it's an event handler for the text box being updated, this function is named changeHandler.

/**
 * Take onChange event and update the text state.
 *
 * @param {event} Event from input
 */
changeHandler(event) {
  // ...
}

Properties

As I'm sure you know, ReactJS components have props that are the same as HTML attributes. It is important the user knows which ones exist and how they can be used. In our example there are a few props, they are:

• defaultText string - initial input value.
• locked boolean - prevent text state updates.
• className string - classes to be added to the component.

Imports

We'll be using propTypes to document the props. This means we'll need to import PropTypes, which comes with ReactJS. It's simple enough we'll just add this line at the top of the document (after our React import).

import React from 'react';
import PropTypes from 'prop-types';

PropTypes

Now let's add the code. After the main class, or function, we need to add an object called ComponentName.propTypes, this object will also contain our documentation.

HelloWorld.propTypes = {
  /**
   * defaultValue String - initial input value
   */
  defaultValue: React.PropTypes.string,
  /**
   * className String - classes to be added to the component
   */
  className: React.PropTypes.string,
  /**
   * locked Boolean- prevent `text` state updates
   */
  locked: React.PropTypes.bool,
}

This has helped us in a couple of ways, not only can we see all the properties we can add but now ReactJS knows what each property should be and will give an error in the console letting the user know exactly what they've done wrong.

Finishing up

These are some simple ways to comment your code along the way. With these simple changes your code will be easy to pick up and understand, be it for you, or even other people that may have access to it down the road. Also all these simple comments are JSDoc compliant so you can easily export documentation as a page.

Thank you for reading. I hope these small tips make your development time easier and maybe even a little more fun. If you have any questions, or any feedback for me, feel free to comment down below.
🦄🧠🦄🦄❤🦄💕🧠🧠❤💕