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.
The added description will appear in a tooltip when you use the function.
We’ve added a JSDoc with a description. We will now look at different types of information we could include.
Parameters (@param
):
We can use @param
to indicate the function’s parameters and describe them.
Additionally, you can specify the parameter data type using curly braces {}
.
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.
Usage Example (@example
):
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.
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.
Custom types (@typedef):
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.
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.
React Hooks:
We can document our hooks so that other developers can get more information regarding the returns in our hooks.
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.
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.