مستند سازی در جاوا

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





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



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



توضیحات خاص : پس از آن مستند می تواند حاوی پاراگراف هایی باشد که هر کدام با واژه ای خاص مانند :@author , @param یا @returns آغاز می شوند و حاوی اطلاعات خاصی در مورد کلاس، اینترفیس، متود یا فیلد هستند.

- همانظور که قبلا گفیتم در تو ضیحات ابتدایی می توان از برخی از تگ های ساده ی HTML استقاده کرد.مثل <I> برای تاکید، <CODE> برای اسم کلاس، اینترفیس، متود یا فیلد و <PRE> برای نمونه کدهای چند خطی. همچنین می تواند شامل تگ های <P> برای ایجاد پاراگراف جدید و <UL>, <LI> و تگ های وابسته برای نمایش لیست ها و ساختارهای مشابه باشند. در مستند نباید از تگ هایی مثل <H2> یا <HR> باشند.

- از بکار بردن تگ <A> برای ایجاد لینک خودداری کنید و بجای آن از تگ {link@} استفاده کنید که برخلاف دیگر تگ های ویژه می تواند در هر جایی آن را به کار برد. تگ {link@} به شما این امکان ایجاد لینک به کلاسها، اینترفیس ها متودها و فیلد ها را بدون دانستن ساختار HTML میدهد.



تگ های ویژه



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



@author name



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


1
2
3
@author David Flanagan
@author Paula Ferguson


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



@version text



این تگ شامل متنی مشخص است.

1
2
@version 1.32, 08/26/99


این تگ بایستی برای هر کلاس و اینترفیسی بکار رود ولی نمی تواند برای متودها یا فیلدها بکار رود.



@param parameter-name description



پارامتر های مشخص شده را با توضیحات آنها در بخش Parameters متود مورد نظر نمایش میدهد. مستند های متود ها با سازنده ها باید شامل یک تک @param برای هر پارامتر ورودی باشند. ای تگ ها باید به همان ترتیب ورودی های متود نوشته شده باشند. این تگ نمی تواند برای کلاس، اینترفیس یا فیلد بکار رود.

1
2
3
@param o the object to insert
@param index the position to insert it at


@return description



بخش Returns را که حاوی توضیحات مشخص شده است را اضافه می کند. این تگ باید برای هر متودی بکار رود مگر اینکه متود void بوده یا سازنده باشد. این تگ نباید برای کلاس، اینترفیس یا فیلد بکار رود.

1
2
3
4
@‬return `true` if the insertion is successful, or
‏ `false` if the list already contains the
‏ specified object.


@exception full-classname description



بخش Throws را که حاوی exception و توضیح مشخص شده است را به مستند اضافه می کند. این تگ بایستی برای هر exception چک شده در شرط throws در متود یا سازنده نوشته شود. بعنوان مثال:

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


از این تگ می توان برای exception هایی که چک نشده اند ولی احتمال وقوع انها وجود دارند نیز استفاده کرد. اگر متودی بیش از یک exception بتواند ایجاد کند برای هر یک از آنها یک تگ نوشته وآنها را بترتیب الفبا مرتب کنید. این تگ نمی تواند برای کلاس، اینترفیس یا فیلد بکار رود. تگ @throws نیز همانند تگ @exception است.



@throws full-classname description



این تگ مانند تگ @exception میباشد. در نسخه ی ۱.۲ جاوا طراحی شده.



@see reference



این تگ مرجع های مشخص شده را در بخش See Also به مستند شما اضافه میکند. reference می تواند در مدل های مختلفی داشته باشد. اگر با quote character (علامت " ' ") آغاز شود به معنی نام کتاب یا دیگر متن های مرجع می باشد. اگر با < آغاز شود این تگ همانند تگ <a> در HTML عمل کرده به لینکی به مرجع شما خواهد بود.

اگر reference با " ' " با " < " آغاز نشود این تگ به فرم کلی زیر است

1
2
@see feature label


که در این صورت متن label نمایش داده شده و با feature مشخص شده اشاره می کند، اگر label نوشته نشود اسم feature بجای ان نمایش داده می شود.

feature می تواند به یک پکیج، کلاس، اینترفیس، متود، سازنده یا فیلد اشاره کند با استفاده از فرم های زیر:



pkgname

ارجاع به پکیج یاد نوشته شده

1
2
@see java.lang.reflect


pkgname.classname

ارجاع به یک کلاس یا اینترفیس با اسم کامل (اسم پکیج ها) آن.

1
2
@see java.util.List


classname

ارجاع به یک کلاس یا اینترفیس بدون مشخص کردن پکیج آن

1
2
@see List


جاوا خودبخود دنبال این کلاس در بین پکیج ها یا کلاس های import شده می گردد.

classneme#methodname

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

1
2
3
@see java.io.InputStream#reset
@see inputStream#close


این روش مبهم است اگر متود مورد نظر overload شده باشد یا کلای دارای فیلدی به این اسم باشد

classname#methodname(paramtypes)

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

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


#methodname

ارجاع به یک متود overload نشده یا سازنده در کلاس با اینترفیس فعلی یا کلاس های شامل یا در سوپرکلاس ها و سوپر اینترفیس های کلاس یا اینترفیس فعلی.

1
2
@see #setBackgroundColor


#methodname(paramtypes)

ارجاع به یک متود یا سازنده در کلاس با اینترفیس فعلی یا کلاس های شامل یا در سوپرکلاس ها و سوپر اینترفیس های کلاس یا اینترفیس فعلی ، با این فرم می تواند به یک متود overload شده نیز ارجاع داد.

1
2
@see #setPosition(int, int)


classname#fieldname

ارجاع به یک فیلد در کلاس مشخص شده

1
2
@see java.io.BufferredInputStream#buf


#fieldname

ارجاع به یک فیلد در کلاس با اینترفیس فعلی یا کلاس های شامل یا در سوپرکلاس ها و سوپر اینترفیس های کلاس یا اینترفیس فعلی.

1
2
@see #x


{@link reference}



این تگ همانند تگ @see کار می کند با این تفاوت که میتواند در همه جا بکار برده شود و محدود به جای خاصی نیست.از این تگ می توان در توضیحات ابتدایی و یا حتی در تگ های @param، @returns ، @exception ،@deprecated استفاده کرد. اکولاد ها برای مشخص کردن این تگ الزامی هستند.

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


@deprecated explanation



از نسخه ی ۱.۱ جاوا این تگ نشان دهنده ی کلاس، اینترفیس، متود یا فیلدی است که استفاده از آن توصیه نمی شود . این تگ متن explanation را در بخش Deprecated در مستند شما نمایش میدهد. این متن باید مشخص کند که چه زمانی استفاده از کلاس یا اعضای آن توصیه نمی شود و در صورت امکان جایگزینی برای آن معرفی کرده و لینکی به آن موجود باشد.

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


هر چند کامنت ها هنگام کامپایل از دید کامدایلر در نظر گرفته نمی شوند ولی در صورت وجود این تگ کامپایلر کلاس را توصیه نشده علامت گذاری میکند. این باعث ی شود تا به کاربرانی که از این کلاس استفاده می کنند هشدار داده شود.



@since version



مشخص می کند چه زمانی کلاس، اینترفیس، متود یا فیلد چه زمانی به مجموعه افزوده شده است. version مشخص کننده ی شماره ی ورژن با مشخصه ی آن است.

1
2
@since JNUT 3.0


هر کلاس یا اینترفیس می بایست دارای تگ @since باشد و هر متودی که بعد از گسترش اولیه ی کلاس به افزوده می شود نیز باید دارای این تگ باشد.



و چهار تگ دیگر که از توضیح آنان می گذریم.


1
2
3
4
5
@‬serial description
‏‪@‬serialField name type description
‏‪@‬serialData description
‏‪@‬beaninfo info




مستند سازی برای پکیج ها


کامنت های مستند برای کلاس ها، اینترفیس ها، متودها، سازنده ها و فیلد ها در بین کد های جاوا و دقیقا قبل از تعریف آنها نوشته می شوند. javadoc همچنین می تواند مستندات خلاصه پکیج ها را خوانده و نمایش دهد. اگر پکیجی در یک فولدر تعریف شده باشد نه در یک فایل سورس کد، javadoc دنبال مستند پکیج در فایل package.html در فولدر حاوی سورس کد های کلاس های موجود در پکیج می گردد.

‏package.html باید شامل مستندهای پکیج با استفاده از کدهای ساده ی HTML باشد. همچنین می تواند شامل تگ های @see , @link, @deprecated و @since باشد. چون package.html فایل سورس کد جاوا نیست پس برای تعریف مستند نیازی به کامنت های جاوا نیست (نباید بین / و */ قرار بگیرد) و همچنین در تگ های @see و @link باید نام کلاس را بصورت کامل (همراه با نام پکیج ها ) نوشت.

به منظور تعریف package.html برای هر پکیج ، شما می توانید از مستندسازی سطح بالا برای پکیج های متعدد استفاده کنید . با تعریف overview.html در ریشه ی درخت پکیج ها.



کامنت مستند سازنده کلاس FileInputStream

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
/**
* 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);
}


برگرفته از:

JAVA in a NUTSHELL Third Edition. by David Flanagan