Time to JSDoc those files!

During your course of JS development, when you will most probably reach the stage where you started to contribute libraries, API and write your own useful classes for the team. When the time comes then, you may need to practice JSDocs – it will save you alot of time for explaining and giving out tutorial on how your library or code works.

JSDocs in a nutshell is documentation generator for JavaScript, it helps to generate html based documentation automatically provided you placed some annotation remarks on top of each methods and functions you wrote. For more info refer to https://jsdoc.app/about-getting-started.html.

Prerequisite, you will first install a global version of jsdoc to allow the CLI to work in your terminal.

npm install jsdoc -g

I’m using an extension to help me prepped the annotation as well. Its called Complete JSDoc Tags, where you only need to start it by typing /** and press enter after that.

Once installed, restart your terminal and then, fire up the command to see it works.

jsdoc --version

Next, we need to learn how to write some common annotations to our source codes. It is actually, simpler than it seems. Below are the sample class I wrote. I’m going to use this as my example.

1
2
3
4
5

    /**
    */
    async postTo(url, param) {
        return await axios.post( url, JSON.stringify(param) , { timeout: 6000, headers:{ "content-type" : "application/json;charset=UTF-8" } } );                         
    }

Notice in line 1, I have started a remark annotation (above). Code below I’ve inserted some annotation codes specific for JSDoc to pick up to create the documentation needed for the function below (see code below). They start with alias like @param, @return, @example followed by bracket which denotes the data type and the then the description of it.

1
2
3
4
5
6
7
8
9
10
11
12

     /**
     * A standardized way of posting to our server via axios. 
     * 
     * @param {String} url url send to API server e.g. '/api'
     * @param {Object} param the javascript object formed usually for parameter purposes.
     * @return {Awaited}
     * @example
	 * Insert some sample code here to show how it works. 
     */
     async postTo(url, param) {
        return await axios.post( url, JSON.stringify(param) , { timeout: 6000, headers:{ "content-type" : "application/json;charset=UTF-8" } } );                         
    }

Now, supposedly, this js is inside a file called ConnectApi.js. Then, all I need is to fire up the CLI in terminal (make sure I’m the same folder as the file).

jsdoc ConnectApi.js

By default, you will see a new folder appearing known as out, this is where your documentation will be stored. They are just some html files describing your codes. You t then continue the same process to all your other functions.

And to target all js files within a folder, just target the foldername instead of the exact file name.

jsdoc folderName

You can also target jsdoc to create a custom named output folder like below. In my case, I like to output to be in docs folder.

jsdoc folderName -d docs

That’s it. Simple right. Hope this helps!

Comments

comments