A Guide to using JSDoc for React.js | Better Documentation in React

Well-written documentation is very essential for a software project. It provides a reference to how different components and methods work in isolation and how they fit together with each other. If you're building a library or a component for distribution, having good documentation is very essential. Without proper documentation, It'll be next to impossible to understand and use it.

A project may have different types of documentation and Code documentation is one of the most important one. JSDoc is a standard approach to writing code documentation in JavaScript. It is also a documentation generator that is used for the Javascript language. One of the advantages it has is that it works out of the box and has great support with various tools.

Benefits of using JSDoc:

• Great support in Visual Studio Code
• Document while you code
• Auto generate documentation in various formats HTML, README

In this blog, you'll learn how to write JSDoc and use it in our React.js Application. We'll also take a look at how to generate documentation from JSDoc. So, let's get started

Getting Started

If you've written any type of comment in your JavaScript Code then you may already be aware of the single-line comments(#) and block comment(/* */) in JavaScript. JSDoc quite is similar. It just allows you to define more tags and lets you add more information in a structured way.

The standard format of JSDoc is

/**
 * <function description>
 * @param   {<type>} param1 <description>
 * @param   {<type>} param2 <description>
 * @param   {<type>} param3 <description>
 * @return  {<type>}        <description>
 */

An example with a function

/**
 * return full name of the user
 * @param   {string} firstName  First Name of the User
 * @param   {string} lastName   Last Name of the User
 * @return  {string}            Fullname of the user
 */
function getFullName(firstName, lastName) {
  return `${firstName} ${lastName}`
}

The following piece of JSDoc will help VSCode learn more about your function. So, the next time you're using that function it will automatically give you autocompletion and suggestions about its parameters and its return type. If you want you can generate full-blown documentation for it as well (more on that later)

Using JSDoc with React Components

To write JSDoc for our component we'll use a theme(plugin) called better-docs

better-docs is a theme for JSDocs that provides a custom @component plugin. It parses our PropTypes and generates the documentation(with Live Preview) from our React Components. It also has an @example tag which prints a live preview of our components.

Here's a simple component using better-docs

import React from "react"
import PropTypes from "prop-types"

/**
 * Component for showing details of the user.
 *
 * @component
 * @example
 * const age = 21
 * const name = 'Jitendra Nirnejak'
 * return (
 *   <User age={age} name={name} />
 * )
 */
const User = props => {
  const { name, age } = props
  return (
    <p>
      {name} is {age} years old.
    </p>
  )
}

User.propTypes = {
  /**
   * User's name
   */
  name: PropTypes.string.isRequired,
  /**
   * User's age
   */
  age: PropTypes.number,
}

User.defaultProps = {
  text: "Jitendra Nirnejak",
  age: 21,
}

export default User

In the above example, we are creating a component and defining some PropTypes with JSDocs. You can see I have defined a @component which will read the function as a React Component and will generate documentation for it, and the @example tag will help with the Live Preview.

Generating Documentation from JSDoc

To generate HTML from our comments, we need to use jsdoc npm package

We can install it using

$ npm i jsdoc

We'll also need to install better-docs plugin for jsdocs.

$ npm i better-docs

Then we need to create a config file

$ touch jsdoc.conf.json

now add the configuration options in the file

{
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": ["jsdoc", "closure"]
  },
  "source": {
    "include": ["src"],
    "includePattern": ".+\\.js(doc|x)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "plugins": ["plugins/markdown", "better-docs/component"],
  "templates": {
    "better-docs": {
      "name": "My React components"
    }
  },
  "opts": {
    "destination": "docs",
    "recurse": true,
    "readme": "README.md"
  }
}

In the above configuration options, we have defined /src as our source directory which will contain our React.js code. And /docs is our output directory. It will also generate a README.md file in the /docs directory. It will process the .js, .jsx and .jsdoc files. The plugin I am using is markdown which is allowing us to use markdown to format our documentation.

To learn more about JSDoc configuration you can go here.

You can create an npm script that can generate the documentation for you

...
"scripts": {
  ...
    "docs": "jsdoc -c jsdoc.conf.json"
  ...
}
...

At last, you can generate the documentation with the following command

npm run docs

Now the documentation can be found in the /docs directory.

I hope this blog helped you know more about JSDoc and how to write better documentation for your React.js applications. There are a lot of tools that integrate with JSDoc, from tools that generate README to the ones that generate full-blown HTML pages. You can write JSDoc with Typescript which unlocks more features of JSDoc. If you're keen to learn more about it, please check out the documentation and give it a try.

Documentation: https://jsdoc.app/

JSDoc Style Guide: https://github.com/shri/JSDoc-Style-Guide

NPM

Better-docs

Hire reactjs developers to work on React.JS development needs.

- Jitendra Nirnejak