يعد توثيق الكود المناسب أمرًا حيويًا لقابلية الصيانة. باستخدام JSDocs، يمكنك تضمينه مباشرةً داخل التعليمات البرمجية الخاصة بك بحيث يكون دائمًا في متناول يدك.

يعد توثيق التعليمات البرمجية المناسبة جانبًا مهمًا ولكن غالبًا ما يتم تجاهله في تطوير البرامج. كمطور، سوف تكون معتادًا على كتابة تعليمات برمجية نظيفة وفعالة، ولكن قد تكون أقل خبرة في كتابة الوثائق الجيدة.

يعد التوثيق الجيد مفيدًا لأي شخص يعمل على الكود الخاص بك، سواء كان أعضاء آخرين في فريقك، أو أنت نفسك، في وقت لاحق. يمكن أن يوضح سبب قيامك بتنفيذ شيء ما بطريقة معينة أو كيفية استخدام وظيفة معينة أو واجهة برمجة التطبيقات.

بالنسبة لمطوري JavaScript، يعد JSDoc طريقة جيدة لبدء توثيق التعليمات البرمجية الخاصة بك.

ما هو JSDoc؟

يمكن أن يكون توثيق التعليمات البرمجية معقدًا ومملًا. ومع ذلك، فإن المزيد من الناس يدركون فوائد نهج "المستندات كرمز".والعديد من اللغات بها مكتبات تساعد في أتمتة العملية. للحصول على وثائق بسيطة وواضحة وموجزة. مثل لغة Go لديها GoDoc لأتمتة التوثيق من التعليمات البرمجية، لذلك تحتوي JavaScript على JSDoc.

يقوم JSDoc بإنشاء الوثائق عن طريق تفسير التعليقات الخاصة في كود مصدر JavaScript الخاص بك، ومعالجة هذه التعليقات، وإنتاج وثائق مخصصة. ومن ثم يجعل هذه الوثائق متاحة بتنسيق HTML يمكن الوصول إليه.

instagram viewer

يؤدي هذا إلى الاحتفاظ بالوثائق داخل التعليمات البرمجية، لذلك عندما تقوم بتحديث التعليمات البرمجية الخاصة بك، يكون من السهل تحديث الوثائق.

إعداد JSDoc

لقد سهّل منشئو JSDoc البدء وإعداد JSDoc في مشروع JavaScript الخاص بك.

لتثبيت JSDoc محليًا، قم بتشغيل:

npm install --save-dev jsdoc

سيؤدي هذا إلى تثبيت المكتبة في مشروعك باعتبارها تبعية للتطوير.

لاستخدام JSDoc، ستستخدم تعليقات تركيبية خاصة داخل كود المصدر الخاص بك. سوف تكتب جميع تعليقاتك التوثيقية داخل /** و */ علامات. داخل هذه، يمكنك وصف المتغيرات المحددة، والوظائف، ومعلمات الوظيفة، وغير ذلك الكثير.

على سبيل المثال:

/**
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */
functiongetUser(name) {
const User = name;
return User;
}

ال @param و @عائدات تعد العلامات اثنتان من العديد من الكلمات الرئيسية الخاصة التي يدعمها JSDoc لشرح التعليمات البرمجية الخاصة بك.

لإنشاء وثائق لهذا الرمز، قم بتشغيل npx jsdoc متبوعًا بالمسار إلى ملف JavaScript الخاص بك.

على سبيل المثال:

npx jsdoc src/main.js

إذا قمت بتثبيت JSDoc عالميًا، فيمكنك حذف ملف npx العلم والتشغيل:

jsdoc path/to/file.js

سيقوم هذا الأمر بإنشاء ملف خارج مجلد في جذر المشروع الخاص بك. ستجد داخل المجلد ملفات HTML تمثل صفحات الوثائق الخاصة بك.

يمكنك الاطلاع على الوثائق من خلال إعداد خادم ويب محلي لاستضافتهأو ببساطة عن طريق فتح الملف out/index.html داخل المتصفح. فيما يلي مثال على الشكل الذي ستبدو عليه صفحة التوثيق افتراضيًا:

تكوين إخراج JSDoc

يمكنك إنشاء ملف تكوين لتغيير سلوك JSDoc الافتراضي.

للقيام بذلك، قم بإنشاء conf.js ملف وتصدير وحدة JavaScript داخل هذا الملف.

على سبيل المثال:

module.exports = {
 source: {
 includePattern: ".+\\\\.js(doc|x)?$",
 excludePattern: ["node_modules"],
 },
 recurseDepth: 5,
 sourceType: "module",
 opts: {
 template: "path/to/template",
 destination: "./docs/",
 recurse: true,
 },
};

داخل ملف التكوين مختلفة تكوين JSDoc خيارات. ال نموذج يتيح لك الخيار استخدام قالب لتخصيص مظهر الوثائق. يوفر مجتمع JSDoc الكثير قوالب التي يمكنك استخدامها. تتيح لك الحزمة أيضًا إنشاء القوالب المخصصة الخاصة بك.

لتغيير موقع الوثائق التي تم إنشاؤها، قم بتعيين وجهة خيار التكوين إلى الدليل. المثال أعلاه يحدد أ مستندات مجلد في جذر المشروع.

استخدم هذا الأمر لتشغيل JSDoc مع ملف التكوين:

jsdoc -c /path/to/conf.js

لتسهيل تشغيل هذا الأمر، قم بإضافته كملف نصوص دخول داخل الخاص بك package.json ملف:

"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
 },

تستطيع الآن قم بتشغيل أمر البرنامج النصي npm داخل المحطة.

مثال على الوثائق التي تم إنشاؤها باستخدام JSDoc

يوجد أدناه مكتبة حسابية بسيطة بها يضيف و طرح او خصم طُرق.

هذا مثال على تعليمات برمجية JavaScript موثقة جيدًا:

/**
 * A library for performing basic arithmetic operations.
 * @module arithmetic
 */
module.exports = {
/**
 * Adds two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @return {number} The sum of the two numbers.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const sum = arithmetic.add(5, 10);
 * console.log(sum); // 15
 */
 add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a + b;
 },


/**
 * Subtracts the second number from the first number.
 * @param {number} a - The number to subtract from.
 * @param {number} b - The number to subtract.
 * @return {number} The result of the subtraction.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const difference = arithmetic.subtract(10, 5);
 * console.log(difference); // 5
 */
 subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }


return a - b;
 }
//... other methods ...
};

توفر تعليقات JSDoc وصفًا واضحًا وشاملاً للمكتبة وأساليبها، بما في ذلك:

  • وصف المكتبة والغرض منها.
  • معلمات كل طريقة، بما في ذلك نوعها ووصف مختصر.
  • القيمة والنوع الذي ترجعه كل طريقة.
  • الأخطاء التي يمكن أن تحدثها كل طريقة والظروف التي تسببها.
  • مثال على كيفية استخدام كل طريقة.

وتشمل التعليقات أيضا @وحدة علامة للإشارة إلى أن هذا الملف عبارة عن وحدة نمطية وأن ملف @مثال علامة لتوفير مثال التعليمات البرمجية لكل أسلوب.

توثيق كود المطور بالطريقة الصحيحة

كما ترون، JSDoc هي أداة مفيدة جدًا لتبدأ في توثيق كود JavaScript. ومن خلال التكامل السهل، يمكنك إنشاء وثائق سريعة ومفصلة أثناء كتابة التعليمات البرمجية الخاصة بك. يمكنك أيضًا صيانة الوثائق وتحديثها مباشرة في مساحة العمل الخاصة بك.

ومع ذلك، على الرغم من فائدة أتمتة JSDoc، إلا أنه يجب عليك الالتزام بإرشادات معينة حتى تتمكن من إنشاء وثائق عالية الجودة.