جافادوك

الموسوعة الحرة

جافادوك (يُكتب أيضًا JavaDoc أو javadoc ) هو مولد توثيق واجهة برمجة التطبيقات (API) للغة البرمجة جافا . يعتمد جافادوك على المعلومات الموجودة في شفرة مصدر جافا ، ويُنشئ توثيقًا بتنسيق HTML وتنسيقات أخرى عبر الإضافات . [ 1 ] تم تطوير جافادوك بواسطة شركة صن مايكروسيستمز ، وتملكه اليوم شركة أوراكل .

يتم التحكم في محتوى وتنسيق المستند الناتج عبر علامات خاصة في تعليقات شفرة المصدر . ولأن هذه العلامات تُعدّ معيارًا فعليًا وشائعة الاستخدام لتوثيق شفرة جافا، [ 2 ] فإن العديد من بيئات التطوير المتكاملة (IDEs) تستخرج وتعرض معلومات Javadoc أثناء عرض شفرة المصدر، غالبًا عبر تمرير مؤشر الماوس فوق رمز مرتبط. تدعم بعض بيئات التطوير المتكاملة، مثل IntelliJ IDEA و NetBeans و Eclipse ، إنشاء قوالب تعليقات Javadoc. [ 3 ]@tag وقد أعيد استخدام صيغة علامات Javadoc من قِبل مولدات توثيق أخرى، بما في ذلك Doxygen و JSDoc و EDoc و HeaderDoc .

يدعم Javadoc التوسيع عبر doclets وtaglets، مما يسمح بإنشاء تنسيقات إخراج مختلفة وإجراء تحليل ثابت لقاعدة التعليمات البرمجية . على سبيل المثال، يُبلغ JDiff عن التغييرات بين إصدارين من واجهة برمجة التطبيقات (API).

على الرغم من أن البعض ينتقدون Javadoc ومولدات وثائق واجهة برمجة التطبيقات بشكل عام، إلا أن أحد دوافع إنشاء Javadoc هو أن وثائق واجهة برمجة التطبيقات التقليدية (الأقل آلية) غالبًا ما تكون قديمة أو غير موجودة بسبب قيود العمل مثل محدودية توافر الكتاب التقنيين . [ 4 ]

يُعد Javadoc جزءًا من Java منذ إصدارها الأول، ويتم تحديثه غالبًا مع كل إصدار من Java Development Kit . [ 5 ]

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

ترميز

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

فيما يلي مثال على تعليق Javadoc للطريقة:

/** * وصف وظيفة الدالة. * * @param input وصف المعامل. * @return وصف القيمة المُعادة. * @throws Exception وصف الاستثناء. */ public int methodName ( String input ) throws Exception { ... }

بعض وسوم HTML ، مثل <p><h1> <head>و <h2> و <nav><h3>، مدعومة في Javadoc.

تخفيض السعر

ابتداءً من Java 23، يدعم Javadoc معيار Markdown CommonMark في أسطر التعليقات التي تبدأ بـ ///بدلاً من تنسيق الأسطر المتعددة القديم. [ 6 ]

دوكليت

يعمل برنامج Doclet مع Javadoc لاختيار المحتوى المراد تضمينه في التوثيق، وتنسيق عرض المحتوى، وإنشاء الملف الذي يحتوي على التوثيق. [ 7 ] يُكتب برنامج Doclet بلغة Java ويستخدم Doclet API...

الStandardDocletيُنشئ Javadoc المُضمّن وثائق واجهة برمجة التطبيقات (API) كملفات HTML قائمة على الإطارات . تتوفر أدوات Doclets أخرى على الإنترنت ، وغالبًا ما تكون مجانية. يمكن استخدامها للأغراض التالية:

  • إنشاء أنواع أخرى من الوثائق (غير المتعلقة بواجهة برمجة التطبيقات)
  • إخراج البيانات بتنسيق آخر غير HTML، مثل PDF
  • إخراج بتنسيق HTML مع ميزات إضافية مثل البحث أو مع مخططات UML مضمنة تم إنشاؤها من فئات Java

الوسوم

بعض علامات Javadoc المتاحة [ 8 ] مدرجة في الجدول أدناه:

بناء الجملةالاستخدامينطبق علىمنذ
اسم المؤلفيُحدد المؤلف مثل "بات سميث"الفئة، الواجهة، التعداد
{ @docRoot }يمثل المسار النسبي إلى الدليل الجذر للمستند المُنشأ من أي صفحة مُنشأةالفئة، الواجهة، التعداد، الحقل، الأسلوب
@version versionمعلومات الإصدارالوحدة، الحزمة، الفئة، الواجهة، التعداد
@since since-textيصف هذا متى ظهرت هذه الخاصية لأول مرة.الفئة، الواجهة، التعداد، الحقل، الأسلوب
انظر المرجعروابط لعناصر أخرى من الوثائقالفئة، الواجهة، التعداد، الحقل، الأسلوب
@param name descriptionيصف معلمة طريقةطريقة
@return descriptionيصف القيمة المُعادةطريقة
@exception اسم الفئة الوصف @throws اسم الفئة الوصفيصف هذا الاستثناء الذي قد يتم طرحه من هذه الطريقةطريقة
وصف مهمليشير إلى أن هذه الطريقة قديمة.الفئة، الواجهة، التعداد، الحقل، الأسلوب
{ @inheritDoc }ينسخ الوصف من الطريقة المُعاد تعريفهاطريقة التجاوز1.4.0
{ @link reference }رابط إلى رمز آخرالفئة، الواجهة، التعداد، الحقل، الأسلوب
{ @linkplain reference }مطابق لـ {@link}، باستثناء أن تسمية الرابط تُعرض بنص عادي بدلاً من خط الكود.الفئة، الواجهة، التعداد، الحقل، الأسلوب
{ @value #STATIC_FIELD }إرجاع قيمة حقل ثابتالمجال الساكن1.4.0
{ @code literal }يُنسق النص الحرفي بخط الكود؛ وهو ما يعادل{@literal}الفئة، الواجهة، التعداد، الحقل، الأسلوب1.5.0
{ @literal literal }يشير إلى نص حرفي؛ ويُفسر النص المضمن على أنه لا يحتوي على ترميز HTML أو علامات جافا دوك متداخلة.الفئة، الواجهة، التعداد، الحقل، الأسلوب1.5.0
{ @serial literal }يشير إلى حقل قابل للتسلسل افتراضيمجال
{ @serialData literal }يشير إلى البيانات المكتوبة بواسطة writeObject( )أو writeExternal( )الطرقالمجال، الطريقة
{ @serialField literal }يشير إلى ObjectStreamFieldمكونمجال

انظر أيضاً

مراجع

  1. ↑ "Javadoc" . agile.csc.ncsu.edu . مؤرشف من الأصل في 13 يونيو 2017. تم الاطلاع عليه في 12 يناير 2022 .
  2. ↑ "javadoc - مولد وثائق واجهة برمجة تطبيقات جافا" . شركة صن مايكروسيستمز . تم الاطلاع عليه بتاريخ 30-09-2011 ..
  3. ↑ IntelliJ IDEA ، وNetBeans (مؤرشفة بتاريخ 5 أبريل 2017 في Wayback Machine) و Eclipse
  4. ↑ فينرز، بيل؛ جوسلينج، جيمس؛ وآخرون . (8 يوليو 2003). "التصور باستخدام JavaDoc" . artima.com . تم الاطلاع عليه في 19 يناير 2013. عندما أنشأتُ JavaDoc الأصلي في المُصرّف الأصلي، حتى المقربون مني انتقدوه بشدة. وكان الأمر مثيرًا للاهتمام، لأن الانتقاد المعتاد كان: بإمكان كاتب تقني جيد أن يُقدّم عملًا أفضل بكثير مما يُقدّمه JavaDoc. والإجابة هي، حسنًا، نعم، ولكن كم عدد واجهات برمجة التطبيقات (APIs) التي يُوثّقها بالفعل كُتّاب تقنيون جيدون؟ وكم منهم يُحدّثون توثيقهم بشكل كافٍ ليكون مفيدًا؟ 
  5. ↑ "كيفية كتابة تعليقات التوثيق لأداة Javadoc" . شركة صن مايكروسيستمز . تم الاطلاع عليه بتاريخ 30-09-2011 ..
  6. ↑ "JEP 467: تعليقات توثيق Markdown" . OpenJDK . 2023-09-11 . تم الاطلاع عليه بتاريخ 2025-09-10 .
  7. ↑ "نظرة عامة على Doclet" .
  8. ↑ مواصفات تعليق توثيق JavaSE 13