Great Doc Marty! Improve your documentation with the JSDoc api

Whoa Doc, that's heavy.

Documentation is one of the most important parts of our code. Our community repeatedly mentions how writing good documentation helps all of us and how detrimental bad documentation can be for others using our projects. However, writing good documentation isn't easy, requiring some time to get it right. In my last performance review earlier this year, one constructive feedback point from my team lead was to improve how I document my code.

I've been thinking a lot on how I can improve on this point over the course of this year. I began with putting more effort into how I name my functions and variables. I also started to comment out my thought process while programming a particular piece code and then cleaning up those comments before creating my PRs. Both of these practices helped, but then I came across a very useful tool while starting on a new project with a couple members of my team.

Have you ever read over some code and came across a snippet like this?

   /**
    * Transform
    * @param {String} ID - page identification
    * @returns {object}
    */

    function transform(ID) => { 
       return { pageName: ID, title: 'Hello World'}
     }

Initially I was confused, wondering what all that @param business about? Hell, to be quite honest it seemed like a very weird way to write a comment. After doing a bit of digging, I stubbled upon where these were coming from; an API called JSDoc, a subset of phpDocumentor and Javadoc.

JSDocs lays out some guidelines to follow when documenting our code and can once we understand a bit of how it works, we can use it to help generate one of the most important parts of our code, documentation.

Where we're going, we DO need roads

Let's get started with some fundamentals of JSDocs. Taking a look at our example above, the entire structure of our comment (the /** **/ bit) is called a DocBlock and those @param lines are called block tags. DocBlocks are typically found before our code and we use block tags to provide details about what our code is doing. DocBlock can also be placed at the top of any file to document the main code, just be aware that this block should come before anything else and any blocks after it should be separate.

We're not limited to just labeling function parameters inside our block tags, however. The JSDocs API provides tags for @functions, @contractors all the way to identifying the @liscense of our code and @ignore to exclude some code from our documentation. Visit JSDoc documentation to see all the different tags JSDocs provides.

Back to the Features

Many modern IDEs such as VSCode, will support auto completion for code that has been documented with JSDocs, providing use insights into the code along with saving us time!

Another great feature is when we've finished our application/library, JSDocs provides a default HTML file, layout.tmpl, containing all of the information provided inside our DocBlocks! This file is also totally configurable, allowing for custom stylings.

Speaking of configuring JSDocs, support for markdown formatted code inside our DocBlocks is also available via "plugins": [plugins/markdown] inside our config file.

Conclusion

Good documentation is an essential for any project you're working on, especially if you intention is to share it with others. While writing will always be an evolving process, there are tools out there that can help guide you in the right direction. I hope you'll take into consideration either adding JSDoc or another documentation API to your toolbox. Thanks for reading and if you enjoyed this please give it a like or tweet.