Document your Javascript code with JSDoc

Document your Javascript code with JSDoc

JSDoc is an open source API documentation generator for Javascript. It allows developers to document their code through comments.

Introduction

In this post I'll try to cover everything you need to know to get started with JSDoc. I'll also share with you some other cool stuff I learned about it that you might find useful.

Table of contents

  • Installation
  • Usage DocumentExportExport files or foldersExport all files recursivelyUse a configuration file* Other cool stuff about JSDoc Built-in support in VSCodeUse a custom layoutJSDoc and SwaggerKnow any other interesting JSDoc feature? JSDoc is an open source API documentation generator for Javascript. It allows developers to document their code through comments. Here's an example:
/**
 *  Retrieves a single file by id.
 *  @param {string} id File identifier.
 *  @returns {File} File object.
 */
const getFileById = (id) => {
    // ...
}

Once your code is fully documented you can easily generate a website containing all the API documentation by running a simple command. How cool is that?

Here's how the previous code would look like in the generated website:

Installation

Install JSDoc globally through npm using this command:

npm install -g jsdoc

Or use the following command to install it for a single project:

npm install --save-dev jsdoc

More info on installation here

Now, to be honest, even though I've been using JSDoc comments to document my code for a long time, I didn't install this package until a few weeks ago because I didn't actually needed to generate the website. Instead I was just using it with VSCode, but I'll talk about that later in this post.

Usage

Document

To start documenting your code all you have to do is add a comment starting with /** over each block of code you want to document: Modules, methods, classes, functions, etc.

You can keep it simple by just adding a description: ""

/**
 * Retrieves a user by email.
 */
const getByEmail = async (email) => {
    // ...
}

Or you can take full advantage of JSDoc using tags:

/**
 * Retrieves a user by email.
 * @async
 * @method
 * @param {String} email - User email
 * @returns {User} User object
 * @throws {NotFoundError} When the user is not found.
 */
const getByEmail = async (email) => {
    // ...
}

There's a huge list of tags you can choose from to document your code as thoroughly as you as please.

Remember, the more info you add to your comments, the more detailed your API documentation will be. But also, find the amount of detail that feels right to you. It's better to have all your code documented with only a few tags than to have only a few methods fully documented using all the tags because it was too much and you couldn't keep up.

Export

After adding the comments all that's left to do is generate your documentation website:

Export files or folders

Simply call jsdoc and add the path to the file or folder.

jsdoc path/to/my/file.js

To include many files or folders, add all their paths separated by a single space.

Export all files recursively

jsdoc -r .

Use a configuration file

It's likely that you're working on a big project with many files and folders that you want to export, and also some that you need to exclude (I'm looking at you, node_modules). If that's the case you may want to use a JSDoc Configuration file.

Using a configuration file allows us to customize JSDoc behavior, like:

  • Which folders or files should be included and which excluded.
  • How deep JSDoc will go when we use the --recurse option.
  • Apply customizations to the template
  • etc

All you need to do is create a .json file containing the settings you want and then use the -c or --configure option to tell JSDoc to where they are:

jsdoc -c /path/to/conf.json

Here's a (very simple) example that I often use:

{
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",   // Only process file ending in .js, .jsdoc or .jsx
        "include": ["."],                       // Check all folders.
        "exclude": ["node_modules"]             // Be gone, node_modules.
    },
    "recurseDepth": 10,                         // Only go 10 levels deep.
    "opts": {
        "destination": "./docs/",               // Where I want my docs to be generated.
        "recurse": true                         // Same as using -r or --recurse
    }
}

Pro tip:> You may want to add the command to your package.json scripts:

"scripts": {
    "generate-docs": "jsdoc -c /path/to/my/conf.js"
}

Then simply use npm run generate-docs from the command-line.

Or you can use sillier names for the script, like: docs-pls, gimme-docs or ill-have-the-large-docs-with-extra-docs (well, maybe not the last one 😅 ).

More info on Configuration here

Other cool stuff about JSDoc

Built in support in VSCode

So, like I said, I was enjoying JSDoc even before installing it, and that's because VSCode has built-in support for JSDoc annotations, which includes:

A snippet that builds the JSDoc annotation structure for you when you type /** (and then press enter) before a function declaration.

Rich hover information

Info about the function signature as you're using it

For more info about JSDoc support in VSCode check VSCode docs.

Use a custom layout

You can create your own template for your API documentation by generating a custom layout.tmpl file and setting the option templates.default.layoutFile to the path of your custom layout in your JSDoc configuration file.

Don't have the time to generate your own template? Here are a few pretty neat template projects you can use:

This project swagger-jsdoc integrates JSDoc with swagger allowing you to write the specification for your routes using the tag @swagger over your block code:

  /**
   * @swagger
   * /:
   *   get:
   *     description: "Returns all users."
   *     responses:
   *       200:
   *         description: "All users were returned."
   */
  app.get('/users', (req, res) => {
    // ...
  });

Know any other interesting JSDoc feature?

===========================================

Thanks for reading :heart: If you liked this post, share it with all of your programming buddies! Follow me on Facebook | Twitter

Learn More

Svelte.js - The Complete Guide

The Complete JavaScript Course 2019: Build Real Projects!

Become a JavaScript developer - Learn (React, Node,Angular)

JavaScript: Understanding the Weird Parts

JavaScript: Coding Challenges Bootcamp - 2019

The Complete Node.js Developer Course (3rd Edition)

Angular & NodeJS - The MEAN Stack Guide

NodeJS - The Complete Guide (incl. MVC, REST APIs, GraphQL)

Node.js Absolute Beginners Guide - Learn Node From Scratch

javascript web-development

Bootstrap 5 Complete Course with Examples

Bootstrap 5 Tutorial - Bootstrap 5 Crash Course for Beginners

Nest.JS Tutorial for Beginners

Hello Vue 3: A First Look at Vue 3 and the Composition API

Building a simple Applications with Vue 3

Deno Crash Course: Explore Deno and Create a full REST API with Deno

How to Build a Real-time Chat App with Deno and WebSockets

Convert HTML to Markdown Online

HTML entity encoder decoder Online

Hire Web Developer

Looking for an attractive & user-friendly web developer? HourlyDeveloper.io, a leading web, and mobile app development company, offers web developers for hire through flexible engagement models. You can **[Hire Web...

Why Web Development is Important for your Business

With the rapid development in technology, the old ways to do business have changed completely. A lot more advanced and developed ways are ...

Important Reasons to Hire a Professional Web Development Company

    You name the business and I will tell you how web development can help you promote your business. If it is a startup or you seeking some...

Hire Dedicated eCommerce Web Developers | Top eCommerce Web Designers

Build your eCommerce project by hiring our expert eCommerce Website developers. Our Dedicated Web Designers develop powerful & robust website in a short span of time.

How long does it take to develop/build an app?

This article covers A-Z about the mobile and web app development process and answers your question on how long does it take to develop/build an app.