This content originally appeared on Alligator.io and was authored by Alligator.io
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:
namewhich is a string.typewhich can have one of three values'meat','veggie'or `‘other’.
If we run npm run doc we’ll get:
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;
}
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:
? 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.
This content originally appeared on Alligator.io and was authored by Alligator.io
Alligator.io | Sciencx (2020-03-11T00:00:00+00:00) Automate JavaScript API Documentation with JSDoc. Retrieved from https://www.scien.cx/2020/03/11/automate-javascript-api-documentation-with-jsdoc/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.