Javadoc في Java
وثّق متدًا بتعليق خاص حتى يرى القارئ والأدوات ماذا يأخذ وماذا يُرجع. في Yard.java اكتب متدًا اسمه add يأخذ int x وint y ويُرجع مجموعهما. ضع كتلة /** */ مباشرة فوق add. داخل الكتلة اكتب جملة قصيرة تصف العمل، ثم وَسِم كل معامل بـ @param والنتيجة بـ @return. في main اطبع add(10, 2). ترجم بـ javac Yard.java وشغّل java Yard. يجب أن تُظهر الشاشة 12. اترك قواعد التسمية للصفحة التالية — هذا الدرس شكل تعليق التوثيق، لا اختيار الأسماء.
ضع /** فوق المتد
صفحة debugging طبعت القيم لإيجاد جمع خاطئ. هذه الصفحة تكتب تعليق توثيق فوق متد نظيف. افتح Yard.java. أبقِ اسم الفئة العامة Yard. احذف تسميات println المتبقية من debug إن دفنت قصة التوثيق، وعروض equals / == المتبقية، وملفات horn المتبقية من Machine، وأي Scanner للوحة المفاتيح. لا ينتظر البرنامج الكتابة. لا تحتاج سطر import لهذا العرض.
داخل Yard أبقِ متدًا صغيرًا وmain قصيرًا. يجب أن تجلس كتلة التوثيق مباشرة فوق المتد الذي تصفه. سطر فارغ بين */ الختامي وسطر المتد مقبول. لا تخفِ الكتلة داخل main. لا تضع الكتلة تحت جسم المتد.
اكتب بداية التعليق بنجمتين بعد الشرطة المائلة:
/**
ثم اكتب جملة بسيطة تقول ماذا يفعل add. ثم اكتب الوسوم. أغلق بـ:
*/
المتد نفسه يبقى Java عاديًا:
static int add(int x, int y) {
return x + y;
}
Javadoc لا يغيّر كيف يعمل return. يخبر القارئ بما يعد به المتد قبل قراءة كل سطر من الجسم.
public class Yard {
/**
* Adds two numbers.
* @param x first number
* @param y second number
* @return the sum of x and y
*/
static int add(int x, int y) {
return x + y;
}
public static void main(String[] args) {
System.out.println(add(10, 2));
}
}
من المجلد الذي يحوي Yard.java شغّل javac Yard.java. عندما تطابق الأقواس والأقواس المعقوفة والفواصل المنقوطة، لا يكتب javac سطرًا من عنده. ثم شغّل java Yard — وليس java Yard.java. أزل لاحقة .java من أمر التشغيل. أبقِ فئة عامة واحدة في الملف حتى يطابق الاسم Yard.
تُظهر الشاشة 12. امشِ التشغيل مرة. تبدأ Java من Yard.main. الاستدعاء add(10, 2) يدخل المتد وx يحمل عشرة وy يحمل اثنين. سطر return يُرجع اثني عشر. System.out.println يكتب ذلك الرقم. كتلة Javadoc لا تطبع من تلقاء نفسها. الكتلة للقرّاء وأدوات التوثيق. إثبات المبتدئ في هذه الصفحة ما زال تشغيلًا صحيحًا بعد تعليق واضح.
اقرأ كتلة التعليق وأنت تنظر إلى توقيع المتد. الجملة Adds two numbers. تطابق عمل return x + y;. السطر @param x first number يسمّي المعامل الأول. السطر @param y second number يسمّي المعامل الثاني. السطر @return the sum of x and y يسمّي النتيجة. أبقِ إملاء الوسم دقيقًا: @param و@return يستخدمان علامة @ وحروفًا لاتينية.
إن ما زلت ترى x=10 وy=2 ثم 8 من ملف debugging، انتقل إلى ملف تدريس Javadoc وشغّل java Yard مجددًا. إن كتبت فقط // Adds two numbers. فوق المتد، فقد كتبت تعليق سطر عادي، لا كتلة Javadoc. أبقِ شكل النجمتين /** حتى تكون الكتلة توثيقًا، لا ملاحظة سطر واحد.
قل القاعدة بصوت عالٍ وأنت تراقب الشاشة: وثّق فوق المتد، وَسِم المعاملات، وَسِم الإرجاع، ثم ترجم وشغّل لتثبت أن المتد ما زال يعمل. لا تخترع محاضرات تسمية طويلة في هذه الصفحة. التسمية تنتظر الدرس التالي.
اقرأ خريطة الوسوم
جدول قصير يحفظ القطع الثلاث التي كتبتها في التعليق. الافتتاح /** */ يعلّم كتلة توثيق. @param يصف اسم معامل واحد. @return يصف القيمة التي يُرجعها المتد. أبقِ اسم المتد add والاستدعاء add(10, 2) حتى تبقى الشاشة رقمًا واضحًا واحدًا.
الجدول هو الخريطة القصيرة لهذه الصفحة. أولًا تضع الكتلة. ثم توسم المدخلات والمخرج. ثم تتحقق بـ javac وjava Yard. تجنّب التخمين أن أي شكل تعليق هو Javadoc. لا تحذف الكتلة قبل أن تعرف أن البرنامج ما زال يطبع 12.
📊 Beginner Javadoc pieces on Yard
| Piece | What it does |
|---|---|
/** */ |
Marks a documentation comment above a method |
@param |
Describes one parameter by name |
@return |
Describes the value the method returns |
أبقِ الجدول بجانب ملف التدريس وأنت تعدّل. أشر إلى @param x في الملف، ثم إلى int x في التوقيع. أشر إلى @param y، ثم إلى int y. أشر إلى @return، ثم إلى سطر return. لعبة المطابقة هذه هي فكرة المبتدئ كلها في مرور واحد. الأدوات التي تقرأ Javadoc تبحث عن تلك الوسوم. القرّاء البشر يستخدمون الخريطة نفسها عندما يكبر جسم المتد لاحقًا.
إن بقيت عروض debugging قريبة، احتفظ بها كتاريخ. لهذا الدرس شغّل ملف تدريس Javadoc حتى تُظهر الشاشة 12 من add، لا أسطر x= المُسمّاة من صيد الباگ. إن اشتكى javac من فئات عامة مكررة، أبقِ Yard فقط public.
تعليق // العادي ليس Javadoc
سطر يبدأ بـ // ملاحظة لمن يقرأ الملف. مفيد، وهذه الدورة استخدمت تعليقات السطر سابقًا. ليس شكل كتلة التوثيق التي تعلّمها هذه الصفحة. Javadoc للمتد يبدأ بـ /** وينتهي بـ */. وسوم @param و@return تجلس داخل تلك الكتلة.
إن وضعت سلسلة عادية تحت المتد بعد عبارات أخرى، فتلك السلسلة ليست توثيق المتد. كتلة التوثيق يجب أن تكون التعليق الملتصق فوق المتد. أبقِ الكتلة ملتصقة بـ add. أبقِ main خاليًا من مسرح توثيق مزيّف. الاستدعاء في main يبقى طباعة عادية للمجموع المُرجَع.
عندما يكون التعليق خاطئًا وجسم المتد صحيحًا، يمكن لـ javac أن ينجح وما زال java Yard يطبع 12. لذلك تطلب هذه الصفحة قراءة التعليق والتوقيع معًا، لا الشاشة وحدها. الشاشة تثبت الحساب. التعليق يثبت أنك وسمت العقد.
مقارنة مع طباعات debugging
في صفحة debugging أجابت println عما هي أرقامك حقًا عندما بدا الجمع خاطئًا. في هذه الصفحة يجيب Javadoc عما يعد به add قبل أن يغوص القارئ في الجسم. ما زلت تترجم Yard.java وتشغّل java Yard. الرموز الجديدة هي /** و@param و@return فوق متد.
استخدم debugging خرجًا عاديًا كمصباح. يستخدم Javadoc تعليقًا منظمًا كملصق على باب المتد. عندما يطابق الملصق المعاملات والإرجاع، يهدر القارئ وقتًا أقل في التخمين. عندما يغيب الملصق، يمكن للبرنامج أن يعمل — عادة التوثيق ما زالت غائبة.
إن كان ملف debugging ما زال مفتوحًا، قد ترى x=10 وy=2 وجمعًا قديمًا. انتقل إلى ملف Javadoc حتى يطبع main قيمة add(10, 2) ويحمل المتد كتلة التوثيق. أبقِ محاضرات أسلوب التسمية خارج هذه الصفحة. أبقِ إدخال لوحة المفاتيح خارج هذه الصفحة.
قبل التسمية
يمكنك وضع /** */ فوق add، ووسم @param x و@param y و@return، وما زلت ترى 12 بعد java Yard. ترجم Yard.java وشغّل java Yard للعرض المحتفظ به. التعليق أخبر القرّاء بالعقد. الصفحة التالية هي التسمية، حيث تختار أسماء واضحة لما تكتب.
أبقِ عرض add الموثَّق لزوج واضح من تعليق وتشغيل. أبقِ ملفات debugging خارج هذه الصفحة عندما تتدرّب على التوثيق. أبقِ ملفات naming خارج هذه الصفحة حتى ذلك الدرس. هذه العادات الثلاث نقطة تفتيش قبل أن تتقدم. عندما تطابق الوسوم التوقيع وتُظهر الشاشة 12، أدّى Javadoc عمله لهذا الدرس وأنت جاهز للموضوع التالي عن التسمية.
مرّة أخيرة على المجلد: Yard عام واحد، add موثَّق واحد، طباعة واحدة في main، بلا انتظار لوحة مفاتيح، بلا إجبار على قواعد تسمية. شغّل javac Yard.java وjava Yard مرة أخرى على العرض المفتوح. إن ما زالت الشاشة تُظهر 12 والتعليق ما زال فوق add مع @param و@return، فشكل التوثيق متين ويمكن للدورة الانتقال إلى التسمية في الصفحة التالية. فضّل كتلة توثيق واضحة واحدة على متد واحد حتى يعلّم كل قراءة الخريطة نفسها.
🧠 اختبر معرفتك
اختبر معرفتك
تحدى نفسك مع هذا الاختبار التفاعلي واكتشف مدى فهمك للموضوع
📝 التعليمات
- اقرأ كل سؤال بعناية
- اختر أفضل إجابة لكل سؤال
- يمكنك إعادة الاختبار عدة مرات كما تريد
- سيتم عرض تقدمك في الأعلى