Sample code for documentation with JSDoc

Introduction

JSDoc It is an open source tool for generating API documentation in JavaScript. It allows developers to document their code using comments.

Sample code for documentation with JSDoc

Below is an example of how to document a method:

/**
* یک فایل را بر اساس شناسه بازیابی می‌کند.
* @param {string} id شناسه فایل.
* @returns {File} شی فایل.
*/
const getFileById = (id) => {
// کد...
}

Install JSDoc

You can use JSDoc globally using npm Install:

npm install -g jsdoc

Or install for a specific project as follows:

npm install --save-dev jsdoc

How to use JSDoc

Add documentation

To start documenting your code, just add a comment with /** At the top of each code block (modules, methods, classes, functions, etc.) add:

/**
* کاربر را با استفاده از ایمیل بازیابی می‌کند.
*/
const getByEmail = async (email) => {
// کد...
}

You can also use JSDoc tags to add more information:

/**
* کاربر را با استفاده از ایمیل بازیابی می‌کند.
* @async
* @method
* @param {String} email - ایمیل کاربر
* @returns {User} شی کاربر
* @throws {NotFoundError} اگر کاربر پیدا نشود.
*/
const getByEmail = async (email) => {
// کد...
}

Documentation production

After adding comments, to generate the documentation as a website, simply run the following command:

jsdoc path/to/my/file.js

Advanced Tips

Using the configuration file

If your project is large and contains many files and folders, you can use a configuration file to customize JSDoc's behavior:

{
"source": {
"includePattern": ".+\\.js(doc|x)?$", // فقط فایل‌های با پسوند .js، .jsdoc یا .jsx پردازش شوند.
"include": ["."], // تمام پوشه‌ها بررسی شوند.
"exclude": ["node_modules"] // پوشه node_modules نادیده گرفته شود.
},
"opts": {
"destination": "./docs/", // مقصد تولید مستندات.
"recurse": true // پوشه‌ها به صورت بازگشتی بررسی شوند.
}
}

Support in VSCode

The VSCode editor supports JSDoc by default, offering features such as auto-completion of comment structures and displaying function information.

Use a custom template

You can override the default JSDoc format by creating a file layout.tmpl Customize and specify it in the configuration file.

Result

JSDoc is a powerful JavaScript code documentation tool that not only helps developers better understand their code, but also provides automatic API documentation generation.