کامنت ها یا توضیحات موجود در بین کدهای جاوا توضیجاتی هستند در مورد نحوه ی پیاده سازی کدها، توضیحاتی که خواننده آن قطعه بکمک آن می تواند از چگونگی عملکرد آن اطلاع حاصل می کند. در جاوا نوع دیگری از کامنت ها وجود دارند که به عنوان کامنت های مستند (Documentation Comments) شناخته میشوند که توضیحاتی هستند برای استفاده کننده کد شما، تا بداند متود یا کلاس یا فیلد شما چه وظیفه ای دارد و چه کاری را به چه نحو انجام می دهد . توضیحات مستند، توضیحات همانند عادی هستند که بجای */ با **/ شروع می شوند و با /* خاتمه می یابند و برخلاف توضیحات معمولی دارای ساختار خاصی می باشند. توضیحات مستند مستقیما قبل از کلاس، اینترفیس، متود، یا فیلد می آیند و حاوی مستنداتی در مورد آن کلاس، اینترفیس، متود یا فیلد هستند. در مستندها می توان از کدهای ساده ی HTML و تعدادی تگ های خاص برای کارهای خاص استفاده کرد.


ساختار توضیحات مستند


توضیحات آغازی : بدنه ی یک مستند بایستی با جمله ای خلاصه در مورد کلاس، اینترفیس، متود یا فیلد آغاز گردد.این جمله ممکن است بتنهایی بعنوان خلاصه نمایش داده شود پس بایستی مستقل باشد. مستند میتواند با هر تعداد جمله یا عبارت مربوط ادامه پیدا کند.

توضیحات خاص : پس از آن مستند می تواند حاوی پاراگراف هایی باشد که هر کدام با واژه ای خاص مانند :@author , @param یا @returns آغاز می شوند و حاوی اطلاعات خاصی در مورد کلاس، اینترفیس، متود یا فیلد هستند.
- همانظور که قبلا گفیتم در تو ضیحات ابتدایی می توان از برخی از تگ های ساده ی HTML استقاده کرد.مثل <I> برای تاکید، <CODE> برای اسم کلاس، اینترفیس، متود یا فیلد و <PRE> برای نمونه کدهای چند خطی. همچنین می تواند شامل تگ های <P> برای ایجاد پاراگراف جدید و <UL>, <LI> و تگ های وابسته برای نمایش لیست ها و ساختارهای مشابه باشند. در مستند نباید از تگ هایی مثل <H2> یا <HR> باشند.
- از بکار بردن تگ <A> برای ایجاد لینک خودداری کنید و بجای آن از تگ {link@} استفاده کنید که برخلاف دیگر تگ های ویژه می تواند در هر جایی آن را به کار برد. تگ {link@} به شما این امکان ایجاد لینک به کلاسها، اینترفیس ها متودها و فیلد ها را بدون دانستن ساختار HTML میدهد.

تگ های ویژه


همانطور که پیش از این نیز گفتیم در مستند ها می توان از تگ های ویژه ای استفاده کرد که هرکدام از آنها با @ آغاز می شوند. این تگ ها به شما این امکان را می دهند که اطلاعات خاصی را بصورت استاندارد نمایش دهید.

@author name


برای نمایش اسم نویسنده بکار می رود.این تگ بایستی برای هر کلاس یا اینترفیس استفاده شود، ولی نباید این تگ را برای یک متود یا فیلد بصورت مجزا بکار برد. اگر کلاسی دارای چندین نویسنده باشد از چندین تگ در سطر های مجزا استفاده نمایید.

```

@author David Flanagan
@author Paula Ferguson

	اسامی نویسندگان را بترتیب و نویسنده اصلی را در اول بنویسید، اگر نویسنده ی نامشخص باشد می توانید از unascribed استفاده کنید.<br />
	<br />
	<p class="heading left">@version <i>text</i></p><br />
	این تگ شامل متنی مشخص است.<br />

@version 1.32, 08/26/99

	این تگ بایستی برای هر کلاس و اینترفیسی بکار رود ولی نمی تواند برای متودها یا فیلدها بکار رود.<br />
	<br />
	<p class="heading left">@param <i>parameter-name description</i></p><br />
	پارامتر های مشخص شده را با توضیحات آنها در بخش Parameters متود مورد نظر نمایش میدهد. مستند های متود ها با سازنده ها باید شامل یک تک @param برای هر پارامتر ورودی باشند. ای تگ ها باید به همان ترتیب ورودی های متود نوشته شده باشند. این تگ نمی تواند برای کلاس، اینترفیس یا فیلد بکار رود.<br />

@param o the object to insert
@param index the position to insert it at

	<p class="heading left" >@return <i>description</i></p><br />
	بخش Returns را که حاوی توضیحات مشخص شده است را اضافه می کند. این تگ باید برای هر متودی بکار رود مگر اینکه متود void بوده یا سازنده باشد. این تگ نباید برای کلاس، اینترفیس یا فیلد بکار رود.<br />

@‬return true if the insertion is successful, or
false if the list already contains the
‏ specified object.

	<p class="heading left">@exception <i>full-classname description</i></p><br />
	بخش Throws را که حاوی exception و توضیح مشخص شده است را به مستند اضافه می کند. این تگ بایستی برای هر exception چک شده در شرط throws در متود یا سازنده نوشته شود. بعنوان مثال:<br />

@‬exception java.io.FileNotFoundException
‏ If the specified file could not be found

	از این تگ می توان برای exception هایی که چک نشده اند ولی احتمال وقوع انها وجود دارند نیز استفاده کرد. اگر متودی بیش از یک exception بتواند ایجاد کند برای هر یک از آنها یک تگ نوشته وآنها را بترتیب الفبا مرتب کنید. این تگ نمی تواند برای کلاس، اینترفیس یا فیلد بکار رود. تگ @throws نیز همانند تگ @exception است.<br />
	<br />
	<p class="heading left">@throws <i>full-classname description</i></p><br />
	این تگ مانند تگ @exception میباشد. در نسخه ی ۱.۲ جاوا طراحی شده.<br />
	<br />
	<p class="heading left">@see <i>reference</i></p><br />
	این تگ مرجع های مشخص شده را در بخش See Also به مستند شما اضافه میکند. <i>reference</i> می تواند در مدل های مختلفی داشته باشد. اگر با quote character (علامت &quot; &#39; &quot;) آغاز شود به معنی نام کتاب یا دیگر متن های مرجع می باشد. اگر با &lt; آغاز شود این تگ همانند تگ &lt;a&gt; در HTML عمل کرده به لینکی به مرجع شما خواهد بود.<br />
	اگر <i>reference</i> با &quot; &#39; &quot; با &quot; &lt; &quot; آغاز نشود این تگ به فرم کلی زیر است<br />

@see feature label

	که در این صورت متن label نمایش داده شده و با <i>feature</i> مشخص شده اشاره می کند، اگر label نوشته نشود اسم <i>feature</i> بجای ان نمایش داده می شود.<br />
	&rlm;<i>feature</i> می تواند به یک پکیج، کلاس، اینترفیس، متود، سازنده یا فیلد اشاره کند با استفاده از فرم های زیر:<br />
	<br />
	<i>pkgname</i><br />
	ارجاع به پکیج یاد نوشته شده<br />

@see java.lang.reflect

	<i>pkgname.classname</i><br />
	ارجاع به یک کلاس یا اینترفیس با اسم کامل (اسم پکیج ها) آن.<br />

@see java.util.List

	<i>classname</i><br />
	ارجاع به یک کلاس یا اینترفیس بدون مشخص کردن پکیج آن<br />

@see List

	جاوا خودبخود دنبال این کلاس در بین پکیج ها یا کلاس های import شده می گردد.<br />
	&rlm;<i>classneme</i>#<i>methodname</i><br />
	ارجاع به یک متود یا سازنده در در یک کلاس مشخص شده.<br />

@see java.io.InputStream#reset
@see inputStream#close

	این روش مبهم است اگر متود مورد نظر overload شده باشد یا کلای دارای فیلدی به این اسم باشد<br />
	<i>classname</i>#<i>methodname(paramtypes)</i><br />
	ارجاع به یک متود یا سازنده با مشخص کردن نوع ورودی های آن، این مدل زمانی مفید است که مرجع ما یک متود overload شده باشد.<br />

‪@‬see InputStream‪#‬read‪(‬byte‪[],‬ int‪,‬ int‪)

	#<i>methodname</i><br />
	ارجاع به یک متود overload نشده یا سازنده در کلاس با اینترفیس فعلی یا کلاس های شامل یا در سوپرکلاس ها و سوپر اینترفیس های کلاس یا اینترفیس فعلی.<br />

@see #setBackgroundColor

	#<i>methodname(paramtypes)</i><br />
	ارجاع به یک متود یا سازنده در کلاس با اینترفیس فعلی یا کلاس های شامل یا در سوپرکلاس ها و سوپر اینترفیس های کلاس یا اینترفیس فعلی ، با این فرم می تواند به یک متود overload شده نیز ارجاع داد.<br />

@see #setPosition(int, int)

	<i>classname</i>#<i>fieldname</i><br />
	ارجاع به یک فیلد در کلاس مشخص شده<br />

@see java.io.BufferredInputStream#buf

	#<i>fieldname</i><br />
	ارجاع به یک فیلد در کلاس با اینترفیس فعلی یا کلاس های شامل یا در سوپرکلاس ها و سوپر اینترفیس های کلاس یا اینترفیس فعلی.<br />

@see #x

	<p class="heading left">{@link <i>reference</i>}</p><br />
	این تگ همانند تگ @see کار می کند با این تفاوت که میتواند در همه جا بکار برده شود و محدود به جای خاصی نیست.از این تگ می توان در توضیحات ابتدایی و یا حتی در تگ های  `@param، @returns ، @exception ،@deprecated` استفاده کرد. اکولاد ها برای مشخص کردن این تگ الزامی هستند.<br />

@‬param regexp The regular expression to search for. This string
‏ argument must follow the syntax rules described for
‏ {‪@‬link RegExpParser}.

	<p class="heading left">@deprecated <i>explanation</i></p><br />
	از نسخه ی ۱.۱ جاوا این تگ نشان دهنده ی کلاس، اینترفیس، متود یا فیلدی است که استفاده از آن توصیه نمی شود . این تگ متن <i>explanation</i> را در بخش Deprecated در مستند شما نمایش میدهد. این متن باید مشخص کند که چه زمانی استفاده از کلاس یا اعضای آن توصیه نمی شود و در صورت امکان جایگزینی برای آن معرفی کرده و لینکی به آن موجود باشد.<br />

@‬deprecated As of Version 3.0, this method is replaced
‏ by {‪@‬link #setColor}.

	هر چند کامنت ها هنگام کامپایل از دید کامدایلر در نظر گرفته نمی شوند ولی در صورت وجود این تگ کامپایلر کلاس را توصیه نشده علامت گذاری میکند. این باعث ی شود تا به کاربرانی که از این کلاس استفاده می کنند هشدار داده شود.<br />
	<br />
	<p class="heading left">@since <i>version</i></p><br />
	مشخص می کند چه زمانی کلاس، اینترفیس، متود یا فیلد چه زمانی به مجموعه افزوده شده است. <i>version</i> مشخص کننده ی شماره ی ورژن با مشخصه ی آن است.<br />

@since JNUT 3.0

	هر کلاس یا اینترفیس می بایست دارای تگ @since باشد و هر متودی که بعد از گسترش اولیه ی کلاس به افزوده می شود نیز باید دارای این تگ باشد.<br />
	<br />
	و چهار تگ دیگر که از توضیح آنان می گذریم.<br />
 

@‬serial description
‏‪@‬serialField name type description
‏‪@‬serialData description
‏‪@‬beaninfo info

	<br />
<p class="heading">مستند سازی برای پکیج ها</p>
	کامنت های مستند برای کلاس ها، اینترفیس ها، متودها، سازنده ها و فیلد ها در بین کد های جاوا و دقیقا قبل از تعریف آنها نوشته می شوند. <i>javadoc</i> همچنین می تواند مستندات خلاصه پکیج ها را خوانده و نمایش دهد. اگر پکیجی در یک فولدر تعریف شده باشد نه در یک فایل سورس کد، <i>javadoc</i> دنبال مستند پکیج در فایل <i>package.html</i> در فولدر حاوی سورس کد های کلاس های موجود در پکیج می گردد.<br />
	<i>&rlm;package.html</i> باید شامل مستندهای پکیج با استفاده از کدهای ساده ی HTML باشد. همچنین می تواند شامل تگ های @see , @link, @deprecated و @since باشد. چون <i>package.html</i> فایل سورس کد جاوا نیست پس برای تعریف مستند نیازی به کامنت های جاوا نیست (نباید بین /* و **/ قرار بگیرد) و همچنین در تگ های @see و @link باید نام کلاس را بصورت کامل (همراه با نام پکیج ها ) نوشت.<br />
	به منظور تعریف <i>package.html</i> برای هر پکیج ، شما می توانید از مستندسازی سطح بالا برای پکیج های متعدد استفاده کنید . با تعریف <i>overview.html</i> در ریشه ی درخت پکیج ها.<br />
	<br />
	کامنت مستند سازنده کلاس <i>FileInputStream</i></div>

/**
 * Creates a `FileInputStream` by
 * opening a connection to an actual file,
 * the file named by the path name `name`
 * in the file system.  A new `FileDescriptor`
 * object is created to represent this file
 * connection.
 * <p>
 * First, if there is a security
 * manager, its `checkRead` method
 * is called with the `name` argument
 * as its argument.
 * <p>
 * If the named file does not exist, is a directory rather than a regular
 * file, or for some other reason cannot be opened for reading then a
 * `FileNotFoundException` is thrown.
 *
 * @param      name   the system-dependent file name.
 * @exception  FileNotFoundException  if the file does not exist,
 *                   is a directory rather than a regular file,
 *                   or for some other reason cannot be opened for
 *                   reading.
 * @exception  SecurityException      if a security manager exists and its
 *               `checkRead` method denies read access
 *               to the file.
 * @see        java.lang.SecurityManager#checkRead(java.lang.String)
 */
public FileInputStream(String name) throws FileNotFoundException {
    this(name != null ? new File(name) : null);
} 
برگرفته از:
<p style="text-align:left; ">JAVA in a NUTSHELL <i>Third Edition.&nbsp;by David Flanagan</i></p>