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 علامت @ و حروف لاتین دارند.
اگر هنوز از فایل debugging مقدار x=10 و y=2 بعد 8 می‌بینید، به فایل تدریس 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 را اجرا کنید تا صفحه از add مقدار 12 نشان دهد، نه سطرهای برچسب‌دار 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 را برچسب بزنید، و بعد از java Yard هنوز 12 ببینید. برای دموی نگهداشته Yard.java را ترجمه کنید و java Yard را اجرا کنید. توضیح قرارداد را به خواننده گفت. صفحهٔ بعد نام‌گذاری است، جایی که برای آنچه می‌نویسید نام روشن انتخاب می‌کنید.
دموی add مستندشده را برای جفت روشن توضیح‌به‌علاوهٔ اجرا نگه دارید. وقتی تمرین مستند می‌کنید فایل‌های debugging را از این صفحه بیرون بگذارید. فایل‌های naming را تا آن درس از این صفحه بیرون بگذارید. این سه عادت ایست بازرسی قبل از جلو رفتن‌اند. وقتی برچسب‌ها با امضا جور شدند و صفحه 12 نشان داد، Javadoc کار این درس را کرده و برای موضوع بعدی دربارهٔ نام‌گذاری آماده‌اید.
یک‌بار آخر پوشه را ببینید: یک Yard عمومی، یک add مستند، یک چاپ در main، بدون انتظار صفحه‌کلید، بدون اجبار به قواعد نام‌گذاری. یک‌بار دیگر روی دموی باز javac Yard.java و java Yard را اجرا کنید. اگر صفحه هنوز 12 نشان می‌دهد و توضیح هنوز بالای add با @param و @return نشسته، شکل مستند محکم است و دوره می‌تواند در صفحهٔ بعد به نام‌گذاری برود. یک بلوک مستند روشن روی یک متد ترجیح دهید تا هر خواندن همان نقشه را آموزش دهد.
🧠 دانش خود را بیازمایید
دانش خود را بیازمایید
خود را با این آزمون تعاملی به چالش بکشید و ببینید موضوع را چقدر خوب درک کرده‌اید
📝 دستورالعمل‌ها
- هر سوال را با دقت بخوانید
- بهترین پاسخ را برای هر سوال انتخاب کنید
- می‌توانید آزمون را هر چند بار که می‌خواهید تکرار کنید
- پیشرفت شما در بالا نمایش داده می‌شود