English | 简体中文 | 繁體中文 | Русский язык | Français | Español | Português | Deutsch | 日本語 | 한국어 | Italiano | بالعربية
يدعم Java ثلاثة أنواع من التعليقات. الأنواع الأولية هما // و /* */، الثالثة تُدعى تعليقات الوصف، وهي تأتي بـ /** البداية، بـ */النهاية.
تسمح التعليقات بالتضمين في برنامجك معلومات حول البرنامج. يمكنك استخدام برنامج javadoc لإنشاء هذه المعلومات، وإخراجها إلى ملفات HTML.
يشرح التعليقات، مما يجعل من السهل علىك تسجيل معلومات برنامجك.
يكتشف برنامج javadoc العلامات التالية:
| العلامات | وصف | مثال |
|---|---|---|
| @author | تعريف مبرمج الفئة | @author description |
| @deprecated | یک کلاس یا عضو منسوخ شده را مشخص می‌کند | @deprecated توضیح |
| {@docRoot} | مسیر ریشه مستند فعلی را مشخص می‌کند | مسیر دایرکتوری |
| @exception | یک استثنا را برای یک کلاس مشخص می‌کند | @exception نام استثنا توضیح |
| {@inheritDoc} | یک توضیح از مکانیزم والد مستقیم به ارث می‌برد. | یک توضیح از مکانیزم والد مستقیم به ارث می‌برد. |
| {@link} | یک پیوند به یک موضوع دیگر قرار می‌دهد | {@link نام متن} |
| {@linkplain} | یک پیوند به یک موضوع دیگر قرار می‌دهد، اما این پیوند به عنوان متن ساده نمایش داده می‌شود | یک پیوند خطی به یک موضوع دیگر قرار می‌دهد. |
| @param | یک پارامتر روش را توضیح می‌دهد | @param نام پارامتر توضیح |
| @return | نوع نوع بازگشتی را توضیح می‌دهد | @return توضیح |
| @see | یک پیوند به یک موضوع دیگر مشخص می‌کند | @see مکانیزم |
| @serial | یک ویژگی سریال‌سازی را توضیح می‌دهد | @serial توضیح |
| @serialData | داده‌هایی که از طریق روش‌های writeObject( ) و writeExternal( ) نوشته می‌شوند را توضیح می‌دهد | @serialData توضیح |
| @serialField | یک composant ObjectStreamField را توضیح می‌دهد | @serialField نام نوع توضیح |
| @since | برچسب‌گذاری زمانی که یک تغییر خاص معرفی می‌شود | @since روانه |
| @throws | مثل تگ @exception است. | تگ @throws معنای مشابهی با تگ @exception دارد. |
| {@value} | مقدار یک ثابت را نمایش می‌دهد، که باید یک زمینه ثابت باشد. | مقدار یک ثابت را نمایش می‌دهد، که باید یک زمینه ثابت باشد. |
| @version | مشخص کردن نسخه کلاس | @version اطلاعات |
در آغاز /** بعد از آن، سطر اول یا چند سطر اصلی توضیحات مربوط به نوع، متغیرها و روش‌ها هستند.
بعد ذلك، يمكنك تضمين واحد أو أكثر من أنواع مختلفة من @ العلامات. كل @ العلامات يجب أن تكون في بداية سطر جديد أو في بداية سطر يتبعه علامة نجمية (*).
العلامات المتشابهة يجب أن تكون في مجموعة واحدة. على سبيل المثال، إذا كان لديك ثلاثة @see العلامات، يمكنك وضعها بجوار بعضها البعض.
إليك مثال على تعليق شرح فئة:
/*** هذه الفئة ترسم رسمًا بيانيًا من نوع شريطي */ * @author w3codebox * @version 1.2 */
أداة javadoc تأخذ ملفات المصدر الخاصة بك Java كمدخل، وتقوم بإنتاج بعض ملفات HTML تحتوي على تعليقات برامجك.
معلومات كل فئة ستكون في ملف HTML منفرد. يمكن أن تخرج javadoc أيضًا بنية شجرة التركة والفهرس.
تعتمد أداء javadoc على التنفيذ، وقد تختلف الأعمال أيضًا، لذا تحتاج إلى التحقق من إصدار نظام التطوير الخاص بك للاختيار الإصدار المناسب من Javadoc.
إليك مثال بسيط على تعليق الشرح. لاحظ أن كل تعليق يأتي قبل المشروع الذي يصفه.
بعد معالجة javadoc، ستجد تعليقات SquareNum الكلاسيكية في SquareNum.html.
import java.io.*;
/**
* هذه الفئة تظهر التعليقات الوثائقية.
* @author Ayan Amhed
* @version 1.2
*/
public class SquareNum {
/**
* هذه الطريقة تعود مربع العدد.
* هذه وصفة متعددة الأسطر. يمكنك استخدام
* اكتب العديد من السطور كما تريد.
* @param num القيمة التي سيتم مربعها.
* @return مربع العدد.
*/
public double square(double num) {
return num * num;
}
/**
* هذه الطريقة تقرأ عددًا من المستخدم.
* @return القيمة المدخلة كـ double.
* @exception IOException في خطأ الدخول.
* @see IOException
*/
public double getNumber() throws IOException {
InputStreamReader isr = new InputStreamReader(System.in);
BufferedReader inData = new BufferedReader(isr);
String str;
str = inData.readLine();
return (new Double(str)).doubleValue();
}
/**
* هذه الطريقة تظهر square().
* @param args غير مستخدم.
* @return لا شيء.
* @exception IOException في خطأ الدخول.
* @see IOException
*/
public static void main(String args[]) throws IOException
{
SquareNum ob = new SquareNum();
double val;
System.out.println("أدخل القيمة المراد مربعتها: ");
val = ob.getNumber();
val = ob.square(val);
System.out.println("قيمة مربعة هي " + val);
}
}كما يلي، يتم معالجة ملف SquareNum.java باستخدام أداة javadoc:
$ javadoc SquareNum.java تحميل ملف المصدر SquareNum.java... بناء معلومات Javadoc... إصدار Doclet القياسي 1.5.0_13 بناء شجرة لجميع الحزم والفئات... جارى توليد SquareNum.html... SquareNum.java:39: تنبيه - لا يمكن استخدام @return tag في الطريقة ذات نوع العودة void. جارى توليد صفحة إطار الحزمة... جارى توليد صفحة تلخيص الحزمة... إنشاء package-tree.html... إنشاء constant-values.html... بناء مؤشر لجميع الحزم والفئات... إنشاء overview-tree.html... إنشاء index-all.html... إنشاء deprecated-list.html... بناء مؤشر لجميع الفئات... إنشاء allclasses-frame.html... إنشاء allclasses-noframe.html... إنشاء index.html... إنشاء help-doc.html... إنشاء stylesheet.css... 1 تنبيه $