مقدمة
JSDoc أداة مفتوحة المصدر لإنشاء وثائق واجهة برمجة التطبيقات (API) بلغة جافا سكريبت. تتيح للمطورين توثيق أكوادهم باستخدام التعليقات.
عينة من التعليمات البرمجية للتوثيق باستخدام 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 هي أداة قوية لتوثيق كود JavaScript لا تساعد المطورين على فهم الكود الخاص بهم بشكل أفضل فحسب، بل توفر أيضًا إنشاء وثائق API تلقائيًا.
