نوشتن doc comments برای همه apiها

برای آنکه از یک API استفاده شود، باید داکیومنت شده باشد. قبلا این کار به صورت دستی انجام می‌شد اما الان با استفاده از javadoc این کار انجام می‌شود. درواقع javadoc از روی سورس‌کد برای APIها به صورت اتوماتیک داکیومنت با فرمت خاصی می‌سازد.

برای استفاده از این ابزار در محصولات jetbrains از تب tools گزینه Generate java doc رو انتخاب کرده و بعد مکان خروجی رو مشخص می‌کنیم.

از آنجایی که قوانین کامنت‌گذاری برای javaDocs به صورت رسمی جزو زبان جاوا نیستند، هر برنامه‌نویس باید با آن‌ها آشنا باشد.

از جاوا ۴ تا به الان داکیومنت‌های javadoc تغییری نداشته‌اند. به غیر از {@index} که در جاوا ۹ اضافه شده و {@implSpec} که در جاوا ۸ اضافه شده و {@literal} و {@code} که در جاوا ۵ اضافه شده‌اند.

برای آنکه داکیومنت‌های مناسبی داشته باشید باید برای هر کلاس اینترفیس، متد و کانستراکتور کامنت جاوا‌داک نوشته باشید.

در حالت کلی باید هرچیزی که ممکن است خودمان یا کاربران API درباره آن بدانند را در کامنت بنویسیم به طوری که دیگر نیازی به دیدن سورس‌کد و پیاده‌سازی نداشته باشند مثلا اگر کلاسی serializable هست باید serialize form آن را بنویسیم.

کامنت یک متد باید قرارداد بین متد و کلاینت‌اش را به‌طور واضح اما خلاصه توضیح دهد. کامنت متد باید توضیح دهد که متد چه کاری انجام می‌دهد به جای آنکه بگوید چطور انجام می‌دهد. باید تمام pre Condition و post Condition های متد را لیست کند.

معمولا pre conditionها در @throw و یا در @params توضح داده می‌شوند.

علاوه‌بر post conditionها و pre conditionها باید هرگونه ساید‌افکت متد را هم بیان کنیم. مثلا اگر یک متد بک‌گراوند تردی را ران می‌کند باید آن را ذکر کنیم.

کامنت مربوطه باید برای هر آرگومان ورودی یک @param داشته باشد و @return هم ذکر شده باشد مگر آنکه متد void باشد.

همچنین برای هر اکسپشنی که ممکن است متد throw کند باید یک @throw داشته باشیم و جزییات آن را توضیح دهیم.

می توانیم در این کامنت از تگ‌های html استفاده کنیم. اگر بخواهیم تکه کدی بنویسیم می‌توانیم از {@code} استفاده کنیم. مثل : {@code this.size() == 0}

هرکجا که کلاسی را برای inheritance توسعه می‌دهیم باید جزییات پیاده‌سازی و استفاده از آن را هم ذکر کنیم که این کار را با @implSpec انجام می‌دهیم.

اگر بخواهیم از یک سری کاراکتر‌های خاص استفاده کنیم که ممکن است با تگ html اشتباه شوند می‌توانیم از @literal استفاده کنیم.

نکته‌ای که باید به آن توجه کرد آن است که دو متد یا کانستراکتور در کلاس نباید خلاصه یکسانی داشته باشند.

برای آنکه کامنتی را index کنیم هم می‌توانیم از @index استفاده کنیم.

زمانیکه enumها را داکیومنت می‌کنیم باید توجه داشته باشیم که علاوه‌بر خود enum باید تمام مقادیر ثابت داخلی آن را هم داکیومنت کنیم.

این قضیه برای همه اعضای انوتیشن‌ها هم صادق است.

داکیومنت‌های سطح پیکیج هم باید در فایلی به نام package-info.java ذخیره شوند.