JSDoc

السلام عليكم و رحمه الله تعالى و بركاته

هذا الموضوع يعتمد فى بعض اجزائه على ماتم شرحه فى سلسله جافاسكربت الموجهه بالكائنات .

JSDoc هى وسيله لتوثيق أكود الجافاسكربت عن طريق تعليقات ذات معنى كما سنرى لاحقا ، يتم اعراب هذه التعليقات و ينتج عنها توثيق -documentation- فى صوره صفحات HTML ، يمكنك انتاج التوثيق عن طريق استخدام معرب تم برمجته بلغه Perl بإسم JSDoc كما توضح هذه المقاله ، او انتاج التوثيق عن طريق محرر Aptana بضغطه زر و هذا ما سيتناوله هذا الموضوع .

لنفرض ان هناك function constructor لصنف Car يقبل ثلاث عبارات المصنع و الموديل و سنه التصنيع ، هذه العبارات ستكون بمثابه خصائص له كما يوضح الكود البسيط التالى :

function Car(make, model, year){
    this.make = make;
    this.model = model;
    this.year = year;
}

سوف اضيف تعليقات JSDoc داخل block comment بواسطه /**/ لكن عليك ملاحظه ان السطر الاول من التعليق لابد ان يحتوى على اتنين ** كما يوضح الكود البسيط التالى :

/**
* create new Car instance
*@class Car
*@constructor
*@param {String} make the maker of the car ex: BMW
*@param {String} model the model of the car ex: 5-series
*@param {String} year the year of manufacture ex: dd/mm/yyyy
*@return {Object}
*/

function Car(make, model, year){
    this.make = make;
    this.model = model;
    this.year = year;
};

داخل تعليق ال JSDoc الكثير من ال tags ، السطر الاول من التعليق يفيد بأن الوظيفه Car تقوم بإنشاء سيارات جديده ، السطر الثانى يفيد بأن هذه الوظيفه تمثل الصنف Car ، السطر الثالث يفيد بإن هذه الوظيفه constructor للصنف Car ، السطر الرابع داخل التعلق يفيد بأن ال constructor يقبل عباره إسمها make من نوع String و هى مصنع السياره مثل BMW ، و السطر الخامس من التعليق يفيد بأن ال constructor يقبل عباره بإسم model من نوع String و هى موديل السياره مثل الفئه الثالثه ، و السطر الثالث من التعليق يفيد بأن ال constructor يقبل عباره بإسم year من نوع String و هو تاريخ تصنيع السياره بصيغه dd/mm/yyyy ، اما السطر الاخير من التعليق يفيد بأن ال constructor ينتج عنه كائن Object جديد بالطبع من نوع Car .

إذا قمت بكتابه هذه التعليقات قبل الوظيفه Car ، فإن مجرد إستخدام هذه الكود فى محرر Aptana سينتج عنه Code assist يساعدك فى كتابه الكود كما الصوره التاليه :

هناك tags اخرى كثير لتغطيه كل الجوانب التى يمتد اليها الكود التى تكتبه مثل ال encapsulation و العلاقه بين الاصناف و الوراثه و غيره ستجد قائمه كامله هنا .

يمكننا الزياده على المثال السابق بتوثيق الخصائص و الوظائف التى يمتلكها الصنف Car كما يوضح الكود البسيط التالى :

Car.prototype = {
    /**
    * the maker of the car
    *@property make
    *@type {String}
    */
    make:null,
    /**
    * the model of the car
    *@property model
    *@type {String}
    */
    model:null,
    /**
    *the year of manufacture
    *@property year
    *@type {String}
    */
    year:null
    /**
    *start the car and return true, otherwise return false if it can't
    *may be the fuel is empty
    *@method start
    *@memberOf {Car}
    *@return {boolean}
    */
    start:function(){
        //start method code goes here
    }
}

التعليقات السابقه تثوم بتوثيق الخصائص make و model و year و توثق الوظيفه start ، و بالطبع ستظهر التغييرات فى ال code assist فى Aptana كما توضح الصوره التاليه :

إذا قمت بالضغط على زر generate HTML docs الموجود فى شريط الادوات اعلى المحرر Aptana كما توضح الصوره التاليه :

سينتج عنه توثيق HTML فى نفس مسار التطبيق كما توضح الصوره التاليه ، لكنه ليس بجوده التوثيق الذى سينتجه المعرب المكتوب ب Perl الذى اشرت اليه فى اول الموضوع

جميع اطر العمل المشهوره مثل jQuery و Prototype و YUI و ExtJS … الخ موثقه عن طريق JSDoc و جاهز للإستخدام فى Aptana ، و ستجد ان ال code assist فى Aptana يحتوى على توثيق لكل هذه الاطر ، اعتقد انه حان الوقت ان تكتب توثيقك بنفسك لأنه سيساعدك و سيساعد غيرك عند إستخدام ما تكتبه من اكواد ، ووعد على ان اوثق اى كود اكتبه فى المدونه من الان ب JSDoc .

بالمناسبه أيضا هناك مشروع من Yahoo لتوثيق اكواد الجافاسكربت يعد بأنه أفضل من JSDoc بكثير و يقوم بتوليد التوثيق HTML من خلال Interpreter برمجه Python ، لم اطلع عليه حتى الان لكن يمكنك رؤيته من هنا .

الأوسمة: ajax, aptana, documentation, javascript