JS Docs: A Quickstart Guide

JSDocs is a way for us to document and add information to the code we’ve written. This information appears in a tooltip and makes it easier for developers to use our code.

JSDocs is also an API documentation generator that scans files and generates documentation based on the JSDocs documentation added to the files.

You can also convert JSDocs to TypeScript, making it easier to convert from vanilla JavaScript to TypeScript.

This short guide covers all you need to know to apply it in your studies and workplace.

How JSDocs Work:

We add JSDocs to a function by adding a block comment with an opening tag (/**) and a closing tag (**/). Any additional lines between these beginning and closing tags contain an asterisk, *.

Note: The JSDocs you add must be directly above the block of code you are documenting.

In the example below, we have a function that adds two numbers and returns the result. In addition, we’ve added a simple description of what the function will do.

JSDocs: A Basic Example that Contains a Description

The added description will appear in a tooltip when you use the function.

Above: JSDocs showing in our code completion.

Above: JSDocs showing when we are adding our arguments.

We’ve added a JSDoc with a description. We will now look at different types of information we could include.

Parameters (@param):

JSDocs @param documentation

We can use @param to indicate the function’s parameters and describe them.

Additionally, you can specify the parameter data type using curly braces {}.

Above: JSDocs detailing a parameter with @param.

Above: Parameter information shown in the tooltip.

Return (@returns):

You can add a description for the return and the return type.

Note: We don’t specify a parameter name because a return doesn’t have one.

Above: JSDocs detailing the return and return type with @returns

Above: Return information and data type shown in the tooltip.

Usage Example (@example):

JSDocs @example documentation

The @example tag is arguably the most important tag to add to your JSDoc. It allows you to add a code example with syntax highlighting to show how to use the code you’ve written.

Providing a code example speeds up workflow by letting other developers know how to use your code.

Above: JSDocs providing an example of how to use our code.

Above: A code example is shown in the tooltip.

Deprecated code (@deprecated):

JSDocs @deprecated documentation

The @deprecated tag shows that the code has become deprecated. The deprecated function will have a strike-through effect on the function’s name in the code completion. You could provide more information, such as what replacement function to use.

Above: JSDocs deprecated tag to indicate code is deprecated.

Above: The tooltip shows a strike-through effect on the function name and indicates it is deprecated.

Custom types (@typedef):

JSDocs @typedef documentation

We can use the @typedef tag to document custom types.

In the following example, you will see that we add a custom @typedef to document a Person object. Adding this JSDoc information allows us to see the properties available on the parameter that would otherwise not show.

Above: JSDocs @typedef tag to create a custom type for an object.

Above: Code completion from the @typedef tag and information about the properties of our object.

React Components:

We can use JSDocs to document our components.

React components use props. So we will need to use @typedef to create a new custom type for our props object and add our properties to this @typedef custom type.

Note: If you aren’t using TypeScript, you might want to use better-docs. better-docs will save you some steps, and use PropTypes to generate your documentation. We won’t be using `better-docs` in this guide.

In the example below, we’ve created a component called Greeting that displays a greeting message to a user using a name prop that we pass to the component.

Above: JSDocs @typedef tag used to document our component’s props.

Above: The JSDocs we have added to our component.

Above: Tooltip showing the JSDocs props documentation we have added.

React Hooks:

We can document our hooks so that other developers can get more information regarding the returns in our hooks.

Above: JSDocs @typedef used to document our hook’s returns.

Above: The JSDocs we have added for our hook.

Above: Tooltip showing the JSDocs documentation we have added for our hook returns.

Generating JSDocs documentation:

We can generate documentation from the JSDocs we have added to our code.

Installation:

We will first need to install JSDocs, either globally or locally.

Global installation:

npm install -g jsdoc

Local installation:

npm install — save-dev jsdoc

Note: If you’re installing JSDocs locally, you will need to run it from the node_modules folder: ./node_modules/jsdoc/jsdoc.js /src -r. Alternatively, you could add it as a script to your package.json e.g. "jsdocs": "jsdoc /src -r" .

Generating the files:

Once JSDocs is installed, you can run the following command to generate the documentation for a file called `index.js`.

jsdoc index.js

Running JSDocs on a single file isn’t of much use. The following example will run the JSDocs generation recursively for all files in the src directory:

jsdoc src -r

Viewing the documentation:

By default, the documentation will be output to a folder named out.

Inside this folder, you will find an index.html page that you can open with Live Server or similar. Once it’s opened, you will see the documentation that we generated.

Above: Documentation that JSDocs generated.

Closing:

JSDocs can take your code next level when used effectively.

I hope this article has proven helpful and allows you to add the finishing polish you want.

Thanks for your time.