Automate JavaScript API Documentation with JSDoc

Jack Misteli

JSDoc is an amazing tool that allows us to generate API documentation for our JavaScript projects. Let’s go over how to set it up and make use of it.

Setup

To get started with JSDoc, you first need to install it on your machine globally like this:

$ npm i -g jsdoc

Or you can also use JSDoc in an npm project locally:

$ npm init
$ npm i --save-dev jsdoc

Then add the following script to your package.json file:

"doc": "jsdoc -d docs --configure jsconf.json main.js"

main.js is our code’s entry point. The -d flag tells JSDoc in which folder to output the documents. --configure tells JSDoc where the configuration file is located.

What JSDoc does

When we run the command jsdoc, the program will generate HTML files. You can open the HTML files in your browser and navigate it like a regular website.

Defining types

The first thing we want to define in our applications are our data types. We’re going to create a little food application to turn our shopping list into a vegan shopping list.

/**
 * @typedef {Object} Food
 * @property {string} name - What the food should be called
 * @property {('meat' | 'veggie' | 'other')} type - The food's type
 */

In plain English, this code means that we are defining a type called Food which is an Object. Food has two properties:

  • name which is a string.
  • type which can have one of three values 'meat', 'veggie' or `‘other’.

If we run npm run doc we’ll get:

Food type definition inside of JSDoc

Documenting Functions

Here’s how you’d add a comment to a function to document it using JSDoc:

/**
* This function turns a string into a veganized version of the food
* For example 'beef' will turn into 'vegan beef'
* @param {string} food the food item we want to veganize
* @returns {string} the veganized version of our food name
*/
function getVeganFood (food) {
 const veganizedFood = 'vegan ' + food;
 return  veganizedFood;
}

JS doc definition of the getVeganFood function inside of jsdoc

VSCode Integration

You can do some really cool things using VSCode’s IntelliSense. VSCode by default uses JSDoc to prepopulate your documentation. VSCode will use our JSDoc type documentation as a type checker and alert you in the case of a mismatch.

Let’s create a new function:

/**
 * This function will veganize your shopping list
 * It will turn every meat option into a veganized version of the meat
 * For example if we enter
 * @param {Array<Food>} arrayOfFoods Your shopping list
 *  @returns {Array<Food>} the veganized version of our shopping list
 */
const veganizeManyFoods = (arrayOfFoods) => {
 return arrayOfFoods.map(food=> {
  if (food.type === 'veggie')
   console.log('this is a vegetable!')
  // VS Code automatically check if type is one of "meat", "veggie" or "other"
  // it will send an error because 'cheese' is not a food type
  if (food.type === 'cheese')
   food.name = getVeganFood('cheese');

  if(food.type === 'meat'){
   // VS Code send an error because the food object is not a string
   food.name = getVeganFood(food);
  }
  return food;
 });
};

/**
 * The list of items we want to purchase
 * @type {Array<Food>}
 */
const shoppingList = [{
 name:'steak', type: 'meat',
 name:'Chocolate Bar', type: 'snack',
 name:'Artichoke', type: 'veggie'
 }];

/**
 * The vegan version of our shopping list
 * @type {Array<Food>}
 */
const veganShoppingList = veganizeManyFoods(shoppingList);
// in an idea world this should equal
// [
//   { name: 'vegan steak', type: 'meat' },
//   { name: 'Chocolate Bar', type: 'snack' },
//   { name: 'Artichoke', type: 'veggie' }
// ]

Here’s an animated GIF that shows what it will look like in Visual Studio Code:

Gif illustrating how Intellisense can guide you when combined with JSDoc

🚀 This should be enough to get you started with JSDoc. I hope that everything is clear. I also recommend TypeScript users to check out the TypeDoc project. TypeDoc uses a very similar grammar and integrates really well with your existing types.

  Tweet It

🕵 Search Results

🔎 Searching...