إضافة البيانات الوصفية إلى وثائقك
يعد توفير الوثائق الجيدة مهمة أساسية لكل مطور. فهو لا يساعد زملائك على فهم أسبابك بسرعة وربما عملية التفكير فحسب ، بل يساعدك أيضًا على الوصول إلى الكود بشكل أسرع في حالة عودتك إليه بعد شهرين.
لذلك فكرت في إنشاء قائمة (غير كاملة) من العلامات الخاصة لاستخدامها مع تعليقات JSDoc. هذه هي الأشياء التي أستخدمها شخصيًا في أغلب الأحيان والتي أثبتت أنها توفر فائدة حقيقية.
بداية أساسية
يوضح مثال الكود التالي مثالًا بسيطًا أساسيًا يجب استخدامه في كل توثيق. إنه يشرح الغرض والمعلمات وكذلك نوع الإرجاع.
/**
* Get a sum all terms provided.
*
* @param {...number} terms Array of terms to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
رمز المثال في الوثائق
يمكنك تقديم مثال حقيقي للشفرة المضمنة باستخدام علامة "example" لتوضيح حالات استخدام معينة. يمكن أيضًا استخدام هذه العلامة لإظهار حالات الحافة المحتملة بسرعة في سيناريو العالم الحقيقي.
/**
* Get a sum all terms provided.
*
* @example
* ```ts
* import { sum } from "./source";
* const result = sum(40, 2);
* ```
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
عضو في أي وحدة
استخدم علامة "memberOf" لتعريف الوحدة النمطية أو المتغير الأصل الذي يستضيف الكود الموثق.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
تعليق توضيحي للرابط
يمكنك استخدام علامة "see" مع علامة "link" لتوفير وثائق URL منسقة بشكل صحيح ، بدلاً من لصق بعض عناوين URL المضمنة في الوثائق الرئيسية.
/**
* @see (@link module:source.sum}
* @see (@link https://www.some-source.com}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
وثائق النوع العام
إذا كانت التعليمات البرمجية الخاصة بك تستخدم أنواعًا عامة ، فيمكنك استخدام علامة "template" لتحديد اسم النوع العام. يتم استخدام هذا الاسم بعد ذلك في علامات "param" الشائعة كمرجع للنوع.
/**
* @template T
* @param {...T} Array of numbers to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
تحديد مؤلف جزء من الكود
في بعض الحالات ، من المهم إضافة تعليق توضيحي للمؤلف أيضًا. يمكن تحقيق ذلك ببساطة بعلامة "author". لا يمكنك تقديم اسمك فحسب ، بل يمكنك أيضًا تقديم بريد إلكتروني كمرجع للاتصال.
/**
* @author Tom Schönmann <tom@flaming.codes>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
رمز موقوف
ليس هناك الكثير لنقوله عن العلامة "deprecated" ، لأنها تفعل بالضبط ما كنت تتوقعه. تُستخدم هذه العلامة بشكل شائع في واجهات برمجة التطبيقات ويمكنها أيضًا الرجوع إلى الكود الجديد.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
إصدار
استخدم علامة "version" لتوثيق إصدار من الكود المحدد. لاحظ أن هذه العلامة لا تشير إلى إصدار التطبيق ، ولكنها تشير بالفعل إلى إصدارها الخاص. الزيادة في هذا الإصدار تعني أن هذا الرمز المحدد قد تغير.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
منذ متى أصبح الرمز متاحًا للاستخدام
يمكنك استخدام العلامة "since" -tag لتوثيق رقم الإصدار الذي تمت إضافة الكود التالي منه إلى واجهة برمجة التطبيقات العامة. من المهم ملاحظة أن الإصدار يشير الآن إلى نطاق التطبيق. يتناقض هذا مع علامة "version" من قبل ، والتي يتم تحديد نطاقها إلى كتلة التعليمات البرمجية المحددة التي يوثقها.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
