Plugins for Sublime and VS Code that make it easier to write documentation
Yesterday, one of my students pointed out that my in-code documentation always follows the same format. They asked if there are any plugins or references for how I document my code.
I use the JSDoc format for my in-code documentation. I don’t use it to generate HTML documentation or anything, but I do find it a useful standard for explaining how a block of code is supposed to work.
It uses this rough format:
/**
* [Description of the function]
* @param {[type]} [variable name] [description of the parameter/variable]
* @param {[type]} [variable name] [description of the parameter/variable]
* @return {[type]} [description]
*/
Sublime 3 is my text editor of choice. I use the fantastic DocBlockr plugin to make this easier.
When I used VS Code, the Complete JSDoc Tags extension was the best alternative to DocBlockr for Sublime.
With both plugins, you type /** and hit enter/return. They autogenerate the JSDoc header, pulling out variable names and setting things up for you.
Let’s say you have a function that adds two numbers together:
var add = function (num1, num2) {
return num1 + num2;
};
DocBlockr adds this:
/**
* [add description]
* @param {[type]} num1 [description]
* @param {[type]} num2 [description]
*/
var add = function (num1, num2) {
return num1 + num2;
};
The Complete JSDoc Tags extension does something similar.
One annoying quirk with it, though: it splits your cursor onto two lines instead of just focusing on the [add description] line. Still, super useful if you need to write a lot of documentation!