مقدمه
JSDoc یک ابزار متن‌باز برای تولید مستندات API در زبان جاوااسکریپت است. این ابزار به توسعه‌دهندگان امکان می‌دهد تا کدهای خود را با استفاده از نظرات (comments) مستندسازی کنند.
نمونه کد مستندسازی با JSDoc
در زیر نمونه‌ای از نحوه مستندسازی یک متد آورده شده است:
/**
* یک فایل را بر اساس شناسه بازیابی می‌کند.
* @param {string} id شناسه فایل.
* @returns {File} شی فایل.
*/
const getFileById = (id) => {
// کد...
}نصب JSDoc
شما می‌توانید JSDoc را به صورت سراسری با استفاده از npm نصب کنید:
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 را با ایجاد یک فایل layout.tmpl سفارشی کنید و آن را در فایل تنظیمات مشخص کنید.
نتیجه
JSDoc ابزاری قدرتمند برای مستندسازی کدهای جاوااسکریپت است که نه تنها به توسعه‌دهندگان کمک می‌کند کدهای خود را بهتر درک کنند، بلکه تولید مستندات API به صورت خودکار را نیز فراهم می‌کند.
