Пример кода для документации с JSDoc

Введение

JSDoc Это инструмент с открытым исходным кодом для создания документации API на JavaScript. Он позволяет разработчикам документировать свой код с помощью комментариев.

Пример кода для документации с JSDoc

Ниже приведен пример того, как документировать метод:

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

Установить JSDoc

Вы можете использовать JSDoc глобально, используя нпм Установить:

npm install -g jsdoc

Или установите для конкретного проекта следующим образом:

npm install --save-dev jsdoc

Как использовать JSDoc

Добавить документацию

Чтобы начать документировать свой код, просто добавьте комментарий с /** В верхней части каждого блока кода (модулей, методов, классов, функций и т. д.) добавьте:

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

Вы также можете использовать теги JSDoc для добавления дополнительной информации:

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

Производство документации

После добавления комментариев, чтобы создать документацию в виде веб-сайта, просто выполните следующую команду:

jsdoc path/to/my/file.js

Продвинутые советы

Использование файла конфигурации

Если ваш проект большой и содержит много файлов и папок, вы можете использовать файл конфигурации для настройки поведения JSDoc:

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

Поддержка в VSCode

Редактор VSCode по умолчанию поддерживает JSDoc, предлагая такие функции, как автоматическое дополнение структур комментариев и отображение информации о функциях.

Использовать собственный шаблон

Вы можете переопределить формат JSDoc по умолчанию, создав файл макет.tmpl Настройте и укажите его в файле конфигурации.

Результат

JSDoc — мощный инструмент документирования кода JavaScript, который не только помогает разработчикам лучше понимать свой код, но и обеспечивает автоматическую генерацию документации API.