قم بتوثيق كود Java الخاص بك تلقائيًا باستخدام Javadoc

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

توفر Java بشكل ملائم حلاً مدمجًا للمشكلة: Javadoc.

يمكن أن يساعدك جافادوك في توثيق التعليمات البرمجية تلقائيًا

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

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

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

ما هو جافادوك بالضبط وكيف يعمل؟

Javadoc هو برنامج مستقل يأتي مصحوبًا بإصدارات Oracle's Java Development Kit (JDK). في الواقع ، لا يمكنك تنزيله بشكل منفصل. عندما تقوم بتنزيل و تثبيت أحد إصدارات Oracle JDK، سيقوم أيضًا بتثبيت Javadoc.

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

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

يعمل Javadoc عن طريق تحليل التعليقات المنسقة بشكل خاص في التعليمات البرمجية الخاصة بك وتحويلها إلى إخراج HTML. التغيير الوحيد الذي تحتاجه حقًا هو تضمين سلاسل معينة في تعليقاتك. هذه تتيح لجافادوك معرفة ما تريد تضمينه في الوثائق النهائية.

يجب أن تسبق تعليقات Javadoc مباشرةً تصنيف أو حقل أو مُنشئ أو إعلان طريقة. يجب أن يكون التعليق نفسه:

• ابدأ بالأحرف الثلاثة /**.
• قم بتضمين علامة النجمة في بداية كل سطر جديد.
• أغلق مع الحرفين */.

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

إليك مثال لتوضيح تعليقات Javadoc البسيطة التي تصف وظيفة تحصل على صورة من عنوان URL وتطبعها على الشاشة. التعليق يسبق الوظيفة مباشرة ويصف ما تفعله. تستخدم كتلة التعليقات هذه أيضًا ثلاث علامات خاصة بالقسم: param, @إرجاع، و @نرى.

/**
* إرجاع كائن صورة يمكن رسمها على الشاشة.
* يجب أن تحدد الوسيطة url قيمة مطلقة {@حلقة الوصل URL}. الاسم
* الوسيطة عبارة عن محدد متعلق بوسيطة url.
* 

* تعود هذه الطريقة دائمًا على الفور ، سواء أكان ملف
* الصورة موجودة. متي هذه الصغير يحاول رسم الصورة
* الشاشة سيتم تحميل البيانات. الرسوم الأولية
* التي ترسم الصورة سترسم تدريجيًا على الشاشة.
*
* param عنوان url هو عنوان URL مطلق يعطي الموقع الأساسي للصورة
* param اسم موقع الصورة ، بالنسبة إلى وسيطة url
* @إرجاع الصورة على عنوان URL المحدد
* @نرى صورة
*/
عام صورة احصل على الصورة(عنوان URL ، اسم السلسلة){
محاولة {
إرجاع احصل على الصورة(الجديد URL (عنوان url ، الاسم)) ؛
 } قبض على (سوء فهم عنوان URL غير صحيح هـ) {
إرجاعلا شيء;
 }
}

عندما يعالج جافادوك الكود أعلاه ، فإنه ينشئ صفحة ويب مشابهة لما يلي:

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

تُنشئ العلامات @ المستخدمة في نهاية التعليق امتداد المعلمات, عائدات، و أنظر أيضا الأقسام التي تراها.

يجب عليك اتباع param علامة باسم المعلمة ومسافة ووصف لها. في الحالة المذكورة أعلاه ، هناك نوعان من المعلمات: عنوان url و اسم. لاحظ أن كلاهما يظهر تحت عنوان المعلمات نفسه في إخراج التوثيق. يمكنك سرد أكبر عدد ممكن من المعلمات اللازمة للوظيفة أو الطريقة التي تصفها.

ال @إرجاع توثق العلامة القيمة التي ترجعها الدالة ، إن وجدت. يمكن أن يكون وصفًا بسيطًا من كلمة واحدة أو عدة جمل ، حسب الظروف.

ال @نرى تسمح لك العلامة بتمييز الوظائف الأخرى ذات الصلة أو ذات الصلة. في هذه الحالة ، تشير علامةsee إلى وظيفة أخرى تسمى ببساطة صورة. لاحظ أن المراجع التي تمت باستخدام هذه العلامة هي روابط قابلة للنقر ، مما يسمح للقارئ بالانتقال إلى العنصر المشار إليه في HTML النهائي.

يتوفر المزيد من العلامات مثلversion وauthor وexception وغيرها. عند استخدامها بشكل صحيح ، تساعد العلامات في ربط العناصر ببعضها البعض وتجعل من الممكن التنقل عبر الوثائق بسهولة.

تشغيل جافادوك على كود المصدر الخاص بك

يمكنك استدعاء Javadoc في سطر الأوامر. يمكنك تشغيله على ملفات فردية أو أدلة كاملة أو حزم جافا أو عبر قائمة من الملفات الفردية. بشكل افتراضي ، سيقوم Javadoc بإنشاء ملفات توثيق HTML في الدليل حيث تقوم بإدخال الأمر. للحصول على مساعدة بشأن الأوامر المحددة المتاحة ، ما عليك سوى إدخال:

جافادوك --يساعد

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

جافادوك ~/code/اسم الملف.جافا
جافادوك ~/code/* .java

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

لعرض المستندات التي تم إنشاؤها حديثًا ، ما عليك سوى فتح ملف index.html ملف في متصفحك المفضل. ستحصل على صفحة مثل ما يلي:

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

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

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

أفضل 8 مدونات جافا للمبرمجين

اقرأ التالي