پردازش فایل‌های منبع (PROCESS SOURCE FILES)

دستور javadoc فایل‌هایی را که پسوند منبع دارند و سایر فایل‌های شرح داده‌شده در بخش فایل‌های منبع (Source Files) پردازش می‌کند. اگر دستور javadoc را با ارسال نام‌های منفرد فایل‌های منبع اجرا کنید، می‌توانید دقیقاً تعیین کنید که کدام فایل‌های منبع پردازش شوند. با این حال، بیشتر توسعه‌دهندگان بدین صورت کار نمی‌کنند، زیرا ارسال نام بسته‌ها ساده‌تر است. دستور javadoc می‌تواند بدون تعیین صریح نام فایل‌های منبع به سه روش اجرا شود: می‌توانید نام بسته‌ها را ارسال کنید، از گزینهٔ -subpackages استفاده نمایید، یا از نویسه‌های عام (wildcards) همراه با نام فایل‌های منبع بهره ببرید. در این موارد، دستور javadoc تنها در صورتی یک فایل منبع را پردازش می‌کند که فایل تمام شرایط زیر را برآورده سازد:

•

پیشوند نام فایل (با حذف .java) یک نام کلاس معتبر باشد.

•

نام مسیر نسبت به ریشهٔ درخت منبع، پس از تبدیل جداکننده‌ها به نقطه، یک نام بستهٔ معتبر باشد.

•

عبارت package حاوی نام بستهٔ معتبر باشد.

پردازش پیوندها (Processing Links)

در حین یک اجرا، دستور javadoc پیوندهای ارجاع‌متقاطع (cross-reference) را به نام‌های بسته، کلاس و عضوی که بخشی از آن اجرا هستند اضافه می‌کند. پیوندها در مکان‌های زیر ظاهر می‌شوند. برای شرح برچسب‌های @، بخش برچسب‌های Javadoc (Javadoc Tags) را ببینید.

•

اعلان‌ها (انواع بازگشتی، انواع آرگومان‌ها، و انواع فیلدها).

•

بخش‌های همچنین ببینید (See Also) که از برچسب‌های @see تولید شده‌اند.

•

متن درون‌خطی تولید شده از برچسب‌های {@link}.

•

نام استثناها که از برچسب‌های @throws تولید شده‌اند.

•

پیوندهای Specified by به اعضای رابط و پیوندهای Overrides به اعضای کلاس. بخش Method Comment Inheritance را ببینید.

•

جدول‌های خلاصه‌ای که بسته‌ها، کلاس‌ها و اعضا را فهرست می‌کنند.

•

درخت‌های وراثت بسته و کلاس.

•

نمایه (index).

می‌توانید با استفاده از گزینه‌های -link و -linkoffline، پیوندهایی را به متن‌های موجود برای کلاس‌هایی که در خط فرمان گنجانده نشده‌اند (اما به‌طور جداگانه تولید شده‌اند) بیفزایید.

جزئیات پردازش (Processing Details)

دستور javadoc در هر بار اجرا یک سند کامل ایجاد می‌کند. این دستور ساخت افزایشی (incremental build) انجام نمی‌دهد که نتایج اجراهای پیشین را ویرایش کرده یا مستقیماً ادغام کند. با این حال، دستور javadoc می‌تواند به نتایج حاصل از سایر اجراها پیوند دهد.

پیاده‌سازی دستور javadoc به کامپایلر Java نیاز داشته و بر آن متکی است. دستور javadoc بخشی از دستور javac را فرامی‌خواند تا اعلان‌ها را کامپایل کرده و از پیاده‌سازی اعضا چشم‌پوشی کند. دستور javadoc یک بازنمایی درونی غنی از کلاس‌ها شامل سلسله‌مراتب کلاس‌ها و روابط استفاده می‌سازد تا HTML را تولید نماید. دستور javadoc همچنین مستندات ارائه‌شده توسط کاربر را از کامنت‌های مستندسازی در کد منبع استخراج می‌کند. بخش کامنت‌های مستندسازی (Documentation Comments) را ببینید.

دستور javadoc روی فایل‌های منبعی که فایل‌های ساختگیِ صرف (stub files) بدون بدنهٔ متد هستند نیز اجرا می‌شود. این بدان معناست که می‌توانید در مراحل اولیهٔ طراحی پیش از پیاده‌سازی API، کامنت‌های مستندسازی بنویسید و دستور javadoc را اجرا کنید.

اتکا به کامپایلر اطمینان می‌دهد که خروجی HTML دقیقاً با پیاده‌سازی واقعی مطابقت داشته باشد؛ پیاده‌سازی‌ای که ممکن است به‌جای کد منبع صریح، بر کدهای ضمنی متکی باشد. برای نمونه، دستور javadoc سازنده‌های پیش‌فرضی را که در فایل‌های کلاس کامپایل‌شده موجودند ولی در کد منبع وجود ندارند، مستندسازی می‌کند.

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

هنگامی که دستور javadoc ساختار درونی خود را برای مستندسازی می‌سازد، تمام کلاس‌های ارجاع‌داده‌شده را بارگذاری می‌کند. به همین دلیل، دستور javadoc باید بتواند همهٔ کلاس‌های ارجاع‌شده را، اعم از کلاس‌های راه‌انداز (bootstrap classes)، افزونه‌ها (extensions)، یا کلاس‌های کاربر بیابد. به بخش How Classes Are Found در آدرس http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html مراجعه کنید.

به‌طور معمول، کلاس‌هایی که ایجاد می‌کنید باید یا به‌عنوان یک افزونه بارگذاری شوند یا در مسیر کلاس (class path) دستور javadoc قرار گیرند..SS "داکلت‌های JAVADOC (JAVADOC DOCLETS)" شما می‌توانید محتوا و قالب خروجی دستور javadoc را با داکلت‌ها سفارشی‌سازی کنید. دستور javadoc دارای یک داکلت درونی پیش‌فرض به نام داکلت استاندارد (standard doclet) است که مستندات API با قالب HTML تولید می‌کند. شما می‌توانید داکلت استاندارد را تغییر دهید، از آن زیرکلاس بسازید، یا داکلت اختصاصی خود را بنویسید تا خروجی‌هایی در قالب‌های HTML، XML، MIF، RTF یا هر قالب دلخواه دیگری تولید کند.

هنگامی که یک داکلت سفارشی با گزینه -doclet تعیین نشده باشد، دستور javadoc از داکلت استاندارد پیش‌فرض استفاده می‌کند. دستور javadoc دارای گزینه‌های متعددی است که صرف‌نظر از داکلتِ در حال استفاده، در دسترس هستند. داکلت استاندارد مجموعه‌ای تکمیلی از گزینه‌های خط فرمان را ارائه می‌دهد. بخش گزینه‌ها (Options) را ببینید.

فایل‌های منبع کلاس (CLASS SOURCE FILES)

هر کلاس یا رابط (interface) و اعضای آن می‌توانند توضیحات مستندسازی مربوط به خود را در یک فایل منبع داشته باشند. بخش Documentation Comments را ببینید.

فایل‌های توضیحات بسته (PACKAGE COMMENT FILES)

هر بسته می‌تواند توضیحات مستندسازی مربوط به خود را در فایل منبع اختصاصی‌اش داشته باشد که دستور javadoc آن را در صفحه خلاصه بسته (package summary) ادغام می‌کند. شما معمولاً هر مستنداتی را که برای کل بسته اعمال می‌شود در این توضیحات قرار می‌دهید.

برای ایجاد یک فایل توضیحات بسته، می‌توانید توضیحات خود را در یکی از فایل‌های زیر قرار دهید:

•

فایل package-info.java می‌تواند شامل اعلان بسته، حاشیه‌نویسی‌های بسته (package annotations)، توضیحات بسته و برچسب‌های Javadoc باشد. استفاده از این فایل ترجیح داده می‌شود.

•

فایل package.html تنها شامل توضیحات بسته و برچسب‌های Javadoc است و حاشیه‌نویسی‌های بسته را نمی‌پذیرد.

یک بسته می‌تواند یک فایل package.html تکی یا یک فایل package-info.java تکی داشته باشد، اما نباید شامل هر دوی آن‌ها باشد. هر یک از این فایل‌ها را در دایرکتوری بسته در درخت منبع و در کنار فایل‌های منبع خود قرار دهید.

فایل package-info.java

فایل package-info.java می‌تواند شامل توضیح بسته‌ای با ساختار زیر باشد. این توضیح پیش از اعلان بسته قرار می‌گیرد.

نکته: جداکننده‌های توضیح /** و */ باید وجود داشته باشند، اما می‌توان از ستاره‌های ابتدای خطوط میانی صرف‌نظر کرد.

/**

 * Provides the classes necessary to create an  

 * applet and the classes an applet uses 

 * to communicate with its applet context.

 * <p>

 * The applet framework involves two entities:

 * the applet and the applet context.

 * An applet is an embeddable window (see the

 * {@link java.awt.Panel} class) with a few extra

 * methods that the applet context can use to 

 * initialize, start, and stop the applet.

 *

 * @since 1.0

 * @see java.awt

 */

package java.lang.applet;

فایل package.html

فایل package.html می‌تواند شامل توضیح بسته‌ای با ساختار زیر باشد. این توضیح در عنصر <body> قرار می‌گیرد.

فایل: java/applet/package.html

<HTML>

<BODY>

Provides the classes necessary to create an applet and the 

classes an applet uses to communicate with its applet context.

<p>

The applet framework involves two entities: the applet

and the applet context. An applet is an embeddable

window (see the {@link java.awt.Panel} class) with a

few extra methods that the applet context can use to

initialize, start, and stop the applet. 

@since 1.0 

@see java.awt

</BODY>

</HTML>

فایل package.html یک فایل استاندارد HTML است و شامل اعلان بسته نمی‌شود. محتوای این فایل توضیحات، به استثنای یک مورد، به زبان HTML نوشته می‌شود. در توضیحات مستندسازی نباید از جداکننده‌های توضیح /** و */ یا ستاره‌های ابتدای خط استفاده شود. هنگام نوشتن این توضیحات، نخستین جمله را خلاصه‌ای درباره بسته قرار دهید و از گذاشتن عنوان یا هر متن دیگری میان تگ <body> و نخستین جمله خودداری کنید. می‌توانید برچسب‌های بسته را درج کنید. تمام برچسب‌های بلوکی (block tags) باید پس از توضیحات اصلی قرار گیرند. اگر یک برچسب @see در فایل توضیحات بسته اضافه می‌کنید، باید نام کاملاً مشخص (fully qualified name) داشته باشد.

پردازش فایل توضیحات

هنگامی که دستور javadoc اجرا می‌شود، به دنبال فایل توضیحات بسته می‌گردد. در صورت یافتن فایل توضیحات بسته، دستور javadoc مراحل زیر را انجام می‌دهد:

•

توضیحات را جهت پردازش کپی می‌کند. برای package.html، دستور javadoc تمام محتوای میان تگ‌های HTML <body> و </body> را کپی می‌کند. می‌توانید بخش <head> را برای درج تگ <title>، بیانیه حق نشر فایل منبع، یا اطلاعات دیگر اضافه کنید؛ با این حال، هیچ‌کدام از این موارد در مستندات تولیدشده نمایش داده نخواهند شد.

•

برچسب‌های بسته را پردازش می‌کند. بخش Package Tags را ببینید.

•

متن پردازش‌شده را در پایین صفحه خلاصه بسته درج می‌کند. بخش Java Platform, Standard Edition API Specification Overview را در http://docs.oracle.com/javase/8/docs/api/overview-summary.html ببینید.

•

نخستین جمله توضیحات بسته را به بالای صفحه خلاصه بسته کپی می‌کند. دستور javadoc همچنین نام بسته و این نخستین جمله را به فهرست بسته‌ها در صفحه نمای کلی (overview) اضافه می‌کند. بخش Java Platform, Standard Edition API Specification Overview را در http://docs.oracle.com/javase/8/docs/api/overview-summary.html ببینید.

پایان جمله بر اساس همان قواعدی تعیین می‌شود که برای تشخیص پایان جمله نخست توضیحات اصلی کلاس و عضو به کار می‌روند..SS "فایلهای توضیحات مرور کلی (OVERVIEW COMMENT FILES)" هر برنامه یا مجموعه‌ای از بسته‌ها که مستندسازی می‌کنید می‌تواند کامنت توضیحات مرور کلی (overview) مختص به خود را داشته باشد که در فایل مبدأ جداگانه‌ای نگهداری می‌شود و دستور javadoc آن را در صفحهٔ مرور کلیِ تولیدشده ادغام می‌کند. معمولاً در این کامنت هرگونه مستنداتی را قرار می‌دهید که برای کل برنامه یا مجموعهٔ بسته‌ها اعمال می‌شود.

می‌توانید هر نامی که می‌خواهید، مانند overview.html، برای این فایل انتخاب کرده و آن را در هر جایی قرار دهید. یک مکان متداول در بالاترین سطح درخت سورس است.

به‌عنوان مثال، اگر فایلهای سورس بستهٔ java.applet در دایرکتوری /home/user/src/java/applet قرار داشته باشند، می‌توانید یک فایل کامنت مرور کلی در /home/user/src/overview.html بسازید.

می‌توانید برای همان مجموعه فایلهای سورس، چندین فایل کامنت مرور کلی داشته باشید، در صورتی که بخواهید دستور javadoc را چندین بار بر روی مجموعه‌های متفاوتی از بسته‌ها اجرا کنید. برای مثال، می‌توانید دستور javadoc را یک بار با گزینهٔ -private برای مستندات داخلی و بار دیگر بدون این گزینه برای مستندات عمومی اجرا کنید. در این حالت، می‌توانید در جملهٔ نخست هر فایل کامنت مرور کلی، مستندات را به‌صورت عمومی یا داخلی توصیف کنید.

محتوای فایل کامنت مرور کلی، یک کامنت مستندات بزرگ است که با HTML نوشته شده است. جملهٔ نخست را خلاصه‌ای دربارهٔ برنامه یا مجموعهٔ بسته‌ها قرار دهید. بین تگ <body> و جملهٔ نخست، هیچ عنوان یا متن دیگری قرار ندهید. تمام تگ‌ها به‌جز تگ‌های درون‌خطی، مانند تگ {@link}، باید پس از توضیحات اصلی بیایند. اگر یک تگ @see اضافه می‌کنید، باید دارای یک نام کاملاً مشخص (fully qualified name) باشد.

هنگام اجرای دستور javadoc، نام فایل کامنت مرور کلی را با گزینهٔ -overview مشخص کنید. سپس فایل به‌شیوه‌ای مشابه با فایل کامنت بسته پردازش می‌شود. دستور javadoc کارهای زیر را انجام می‌دهد:

•

تمامی محتوای بین تگ‌های <body> و </body> را برای پردازش کپی می‌کند.

•

تگ‌های مرور کلی موجود را پردازش می‌کند. بخش Overview Tags را ببینید.

•

متن پردازش‌شده را در انتهای صفحهٔ مرور کلیِ تولیدشده درج می‌کند. بخش Java Platform Standard Edition API Specification Overview را در http://docs.oracle.com/javase/8/docs/api/overview-summary.html ببینید

•

جملهٔ نخست کامنت مرور کلی را در بالای صفحهٔ خلاصه مرور کلی کپی می‌کند.

فایلهای پردازشنشده (UNPROCESSED FILES)

فایلهای سورس شما می‌توانند شامل هر فایلی باشند که می‌خواهید دستور javadoc آنها را در دایرکتوری مقصد کپی کند. این فایلها معمولاً شامل فایلهای گرافیکی، فایلهای سورس و class نمونهٔ جاوا، و فایلهای HTML مستقلی هستند که محتوای زیاد آنها ممکن است کامنت مستندات یک فایل سورس جاوای معمولی را بیش از حد شلوغ کند.

برای گنجاندن فایلهای پردازشنشده، آنها را در دایرکتوری‌ای به نام doc-files قرار دهید. دایرکتوری doc-files می‌تواند یک زیردایرکتوری از هر دایرکتوری بسته‌ای باشد که شامل فایلهای سورس است. شما می‌توانید برای هر بسته یک زیردایرکتوری doc-files داشته باشید.

برای مثال، اگر می‌خواهید تصویر یک دکمه را در مستندات کلاس java.awt.Button بگنجانید، فایل تصویر را در دایرکتوری /home/user/src/java/awt/doc-files/ قرار دهید. دایرکتوری doc-files را در /home/user/src/java/doc-files قرار ندهید، زیرا java یک بسته نیست و هیچ فایل سورسی در بر ندارد.

تمام پیوندها به فایلهای پردازشنشده باید در کد گنجانده شوند زیرا دستور javadoc به این فایلها نگاه نمی‌کند. دستور javadoc این دایرکتوری و تمام محتویات آن را در مقصد کپی می‌کند. مثال زیر نشان می‌دهد که پیوند در کامنت مستندات Button.java چگونه ممکن است باشد:

/**

 * This button looks like this: 

 * <img src="doc-files/Button.gif">

 */

فایلهای آزمون و الگو (TEST AND TEMPLATE FILES)

می‌توانید فایلهای آزمون و الگو را در درخت سورس، در همان دایرکتوری یا در زیردایرکتوری‌ای از دایرکتوری قرارگیری فایلهای سورس ذخیره کنید. برای جلوگیری از پردازش فایلهای آزمون و الگو، دستور javadoc را اجرا کرده و نام‌های تک‌تک فایلهای سورس را صراحتاً به آن ارسال کنید.

فایلهای آزمون، فایلهای سورس معتبر و قابل کامپایل هستند. فایلهای الگو فایلهای سورس معتبر و سازگار نیستند، اما اغلب پسوند .java دارند.

فایلهای آزمون (Test Files)

اگر می‌خواهید فایلهای آزمون شما به یک بستهٔ بدون نام یا به بسته‌ای غیر از بستهٔ فایلهای سورس تعلق داشته باشند، فایلهای آزمون را در یک زیردایرکتوری در زیر فایلهای سورس قرار دهید و یک نام نامعتبر به آن دایرکتوری اختصاص دهید. اگر فایلهای آزمون را در همان دایرکتوریِ سورس قرار دهید و دستور javadoc را با یک آرگومان خط فرمان که نشان‌دهندهٔ نام بسته است فراخوانی کنید، فایلهای آزمون موجب هشدار یا خطا می‌شوند. اگر فایلها در زیردایرکتوری با نام نامعتبر باشند، دایرکتوری فایلهای آزمون نادیده گرفته شده و هیچ خطا یا هشداری صادر نمی‌شود. برای مثال، برای افزودن فایلهای آزمون برای فایلهای سورس در com.package1، آنها را در زیردایرکتوری‌ای با یک نام بستهٔ نامعتبر قرار دهید. نام دایرکتوری زیر نامعتبر است زیرا حاوی خط پیوند (hyphen) می‌باشد:

com/package1/test-files/

اگر فایلهای آزمون شما حاوی کامنت‌های مستندات هستند، می‌توانید یک اجرای جداگانه از دستور javadoc را با ارسال نام‌های فایلهای سورس آزمون با استفاده از نویسه‌های عمومی (wildcards)، مانند com/package1/test-files/*.java، برای تولید مستندات فایلهای آزمون برپا کنید.

فایلهای الگو (Template Files)

اگر می‌خواهید یک فایل الگو در دایرکتوری سورس باشد، اما هنگام اجرای دستور javadoc خطایی تولید نکند، یک نام فایل نامعتبر مانند Buffer-Template.java به آن بدهید تا از پردازش آن جلوگیری شود. دستور javadoc تنها فایلهای سورسی را پردازش می‌کند که نام آنها پس از حذف پسوند .java، یک نام کلاس معتبر باشد.

صفحه‌های محتوای اصلی (BASIC CONTENT PAGES)

•

یک صفحهٔ کلاس یا رابط (classname.html) برای هر کلاس یا رابطی که مستندسازی می‌شود.

•

یک صفحهٔ بسته (package-summary.html) برای هر بسته‌ای که مستندسازی می‌شود. دستور javadoc هر متن HTML ارائه‌شده در فایلی به نام package.html یا package-info.java در دایرکتوری بسته در درخت سورس را در بر می‌گیرد.

•

یک صفحهٔ مرور کلی (overview-summary.html) برای کل مجموعهٔ بسته‌ها. صفحهٔ مرور کلی صفحهٔ نخست مستندات تولیدشده است. دستور javadoc هر متن HTML ارائه‌شده در فایلی را که توسط گزینهٔ -overview مشخص شده در بر می‌گیرد. صفحهٔ Overview تنها زمانی ایجاد می‌شود که دو یا چند نام بسته را به دستور javadoc بدهید. بخش‌های HTML Frames و گزینه‌ها (Options) را ببینید.

صفحه‌های ارجاع متقابل (CROSS-REFERENCE PAGES)

•

یک صفحهٔ سلسله‌مراتب کلاس برای کل مجموعهٔ بسته‌ها (overview-tree.html). برای مشاهدهٔ صفحهٔ سلسله‌مراتب، روی Overview در نوار ناوبری و سپس روی Tree کلیک کنید.

•

یک صفحهٔ سلسله‌مراتب کلاس برای هر بسته (package-tree.html). برای مشاهدهٔ صفحهٔ سلسله‌مراتب، به صفحهٔ یک بسته، کلاس یا رابط خاص بروید و برای نمایش سلسله‌مراتب آن بسته، روی Tree کلیک کنید.

•

یک صفحهٔ استفاده برای هر بسته (package-use.html) و یک صفحهٔ استفادهٔ مجزا برای هر کلاس و رابط (class-use/classname.html). صفحهٔ استفاده شرح می‌دهد که چه بسته‌ها، کلاس‌ها، متدها، سازنده‌ها و فیلدهایی از هر بخش از کلاس، رابط یا بستهٔ مشخص‌شده استفاده می‌کنند. برای مثال، با فرض یک کلاس یا رابط A، صفحهٔ استفادهٔ آن شامل زیرکلاس‌های A، فیلدهای اعلان‌شده به‌صورت A، متدهایی که A برمی‌گردانند، و متدها و سازندگانی با پارامترهایی از نوع A است. برای مشاهدهٔ صفحهٔ استفاده، به بسته، کلاس یا رابط رفته و روی پیوند Use در نوار ناوبری کلیک کنید.

•

یک صفحهٔ API منسوخ‌شده (deprecated-list.html) که تمام APIهای منسوخ‌شده و جایگزین‌های پیشنهادی آنها را فهرست می‌کند. از APIهای منسوخ‌شده اجتناب کنید زیرا ممکن است در پیاده‌سازی‌های آینده حذف شوند.

•

یک صفحهٔ مقادیر فیلدهای ثابت (constant-values.html) برای مقادیر فیلدهای استاتیک.

•

یک صفحهٔ فرم سریال‌سازی‌شده (serialized-form.html) که اطلاعاتی دربارهٔ کلاس‌های قابل سریال‌سازی و قابل برون‌ریزی به همراه شرح فیلدها و متدها ارائه می‌دهد. اطلاعات این صفحه برای پیاده‌سازان مجدد کاربرد دارد و نه برای توسعه‌دهندگانی که می‌خواهند از API استفاده کنند. برای دسترسی به صفحهٔ فرم سریال‌سازی‌شده، به هر کلاس سریال‌سازی‌شده بروید و در بخش See Also کامنت کلاس، روی Serialized Form کلیک کنید. doclet استاندارد یک صفحهٔ فرم سریال‌سازی‌شده تولید می‌کند که هر کلاسی (عمومی یا غیرعمومی) را که Serializable را به همراه متدهای readObject و writeObject آن، فیلدهایی که سریال‌سازی می‌شوند، و کامنت‌های مستندات ناشی از تگ‌های @serial، @serialField، و @serialData پیاده‌سازی کرده است فهرست می‌کند. کلاس‌های سریال‌پذیر عمومی را می‌توان با علامت‌گذاری آنها (یا بستهٔ آنها) با @serial exclude مستثنی کرد، و کلاس‌های سریال‌پذیر با سطح دسترسی بسته را می‌توان با علامت‌گذاری آنها (یا بستهٔ آنها) با یک @serial include گنجاند. از نگارش 1.4 به بعد، می‌توانید فرم کامل سریال‌سازی‌شده را برای کلاس‌های عمومی و خصوصی با اجرای دستور javadoc بدون مشخص کردن گزینهٔ -private تولید کنید. بخش گزینه‌ها (Options) را ببینید.

•

یک صفحهٔ نمایه (index-*.html) از تمام نام‌های کلاس‌ها، رابط‌ها، سازنده‌ها، فیلدها و متدها، به ترتیب حروف الفبا. صفحهٔ نمایه برای یونیکد بین‌المللی‌سازی شده است و می‌تواند به‌عنوان یک فایل واحد یا به‌عنوان یک فایل جداگانه برای هر نویسهٔ آغازین (مانند A–Z برای انگلیسی) تولید شود.

صفحه‌های پشتیبانی (SUPPORT PAGES)

•

یک صفحهٔ راهنما (help-doc.html) که نوار ناوبری و صفحه‌های قبلی را شرح می‌دهد. از -helpfile برای بازنویسی فایل راهنمای پیش‌فرض با فایل راهنمای سفارشی خود استفاده کنید.

•

یک فایل index.html که فریم‌های HTML را برای نمایش ایجاد می‌کند. این فایل را برای نمایش صفحهٔ نخست همراه با فریم‌ها بارگذاری کنید. فایل index.html هیچ محتوای متنی ندارد.

•

چندین فایل فریم (*-frame.html) که حاوی فهرست‌هایی از بسته‌ها، کلاس‌ها و رابط‌ها هستند. فایلهای فریم، فریم‌های HTML را نمایش می‌دهند.

•

یک فایل فهرست بسته (package-list) که توسط گزینه‌های -link و -linkoffline استفاده می‌شود. فایل فهرست بسته یک فایل متنی است که از طریق پیوندها قابل دسترسی نیست.

•

یک فایل برگه‌سبک (stylesheet.css) که مقدار محدودی از رنگ، خانوادهٔ قلم، اندازهٔ قلم، سبک قلم و اطلاعات جای‌گیری در صفحه‌های تولیدشده را کنترل می‌کند.

•

یک دایرکتوری doc-files که فایلهای تصویری، نمونه، کد منبع یا دیگر فایلهایی را که می‌خواهید در دایرکتوری مقصد کپی شوند نگهداری می‌کند. این فایلها توسط دستور javadoc پردازش نمی‌شوند. این دایرکتوری پردازش نمی‌شود مگر اینکه در درخت سورس وجود داشته باشد.

بخش گزینه‌ها (Options) را ببینید..SS "فریم‌های HTML (HTML FRAMES)" دستور javadoc بر اساس مقادیر ارائه‌شده به آن، حداقل تعداد فریم‌های ضروری (دو یا سه) را تولید می‌کند. هنگامی که تنها یک نام بسته یا فایل‌های منبع متعلق به یک بسته واحد را به عنوان آرگومان به دستور javadoc می‌دهید، این دستور از فهرست بسته‌ها صرف‌نظر می‌کند. در عوض، دستور javadoc یک فریم در ستون سمت چپ ایجاد می‌کند که فهرست کلاس‌ها را نمایش می‌دهد. هنگامی که دو یا چند نام بسته را ارسال می‌کنید، دستور javadoc فریم سومی ایجاد می‌کند که همه بسته‌ها و یک صفحه مرور کلی (overview-summary.html) را فهرست می‌کند. برای گذر از فریم‌ها، روی پیوند No Frames کلیک کنید یا از صفحه overview-summary.html وارد مجموعه صفحات شوید.

ساختار فایل‌های تولیدشده (GENERATED FILE STRUCTURE)

فایل‌های کلاس و رابط (interface) تولیدشده در همان سلسله‌مراتب پوشه‌ای سازمان‌دهی می‌شوند که فایل‌های منبع و فایل‌های کلاس جاوا سازمان‌دهی شده‌اند. این ساختار شامل یک پوشه به ازای هر زیربسته (subpackage) است.

برای نمونه، سند تولیدشده برای کلاس java.applet.Applet در مسیر java/applet/Applet.html قرار خواهد گرفت.

ساختار فایل برای بسته java.applet با فرض اینکه نام پوشه مقصد apidocs باشد، در ادامه آمده است. تمام فایل‌هایی که شامل واژه frame هستند، همان‌طور که اشاره شده در فریم‌های بالا-چپ یا پایین-چپ ظاهر می‌شوند. تمام فایل‌های HTML دیگر در فریم سمت راست نمایش داده می‌شوند.

پوشه‌ها پررنگ (bold) هستند. علامت‌های ستاره (*) نشان‌دهنده فایل‌ها و پوشه‌هایی است که اگر آرگومان‌های ارائه‌شده به دستور javadoc به جای نام بسته‌ها، نام فایل‌های منبع باشند، حذف می‌شوند. هنگامی که آرگومان‌ها نام فایل‌های منبع باشند، یک فهرست بسته خالی ایجاد می‌شود. پوشه doc-files در مقصد ایجاد نمی‌شود مگر اینکه در درخت منبع وجود داشته باشد. به بخش Generated Files مراجعه کنید.

•

apidocs: پوشه سطح بالا

•

java: پوشه بسته

•

src-html: پوشه کد منبع

public final class Boolean

extends Object

implements Serializable

public static Boolean valueOf(String s)

کامنت‌های کد منبع (SOURCE CODE COMMENTS)

می‌توانید کامنت‌های مستندسازی را در کد منبع، پیش از اعلان‌های هر کلاس، رابط، متد، سازنده یا فیلد قرار دهید. همچنین می‌توانید کامنت‌های مستندسازی را برای هر بسته (package) و یک مورد دیگر را برای نمای کلی (overview) ایجاد کنید، هرچند ساختار دستوری (syntax) آن‌ها کمی متفاوت است. یک کامنت مستندسازی از نویسه‌های میان /** و */ پایانی تشکیل می‌شود. ستاره‌های ابتدایی در هر خط مجاز هستند و در بخش بعدی بیشتر شرح داده شده‌اند. متن موجود در یک کامنت می‌تواند در چندین خط ادامه یابد.

/**

 * This is the typical format of a simple documentation comment

 * that spans two lines.

 */

برای صرفه‌جویی در فضا می‌توانید یک کامنت را در یک خط قرار دهید:

/** This comment takes up only one line. */

محل قرارگیری کامنت‌ها (Placement of Comments)

کامنت‌های مستندسازی تنها زمانی شناسایی می‌شوند که بلافاصله پیش از اعلان‌های کلاس، رابط، سازنده، متد یا فیلد قرار گیرند. کامنت‌های مستندسازی قرار داده شده در بدنه‌ی یک متد نادیده گرفته می‌شوند. دستور javadoc برای هر عبارت اعلان، تنها یک کامنت مستندسازی را به رسمیت می‌شناسد. بخش Where Tags Can Be Used را ببینید.

یک اشتباه رایج، قرار دادن عبارت import بین کامنت کلاس و اعلان کلاس است. در این مکان عبارت import قرار ندهید زیرا دستور javadoc کامنت کلاس را نادیده می‌گیرد.

/**

 * This is the class comment for the class Whatever.

 */

import com.example;   // MISTAKE - Important not to put import statement here

public class Whatever{ }

بخش‌های کامنت (Parts of Comments)

یک کامنت مستندسازی دارای یک بخش توضیحات اصلی است که بخش تگ‌ها پس از آن می‌آید. توضیحات اصلی پس از جداکننده‌ی آغازین /** شروع شده و تا بخش تگ‌ها ادامه می‌یابد. بخش تگ‌ها با نخستین تگ بلوکی (block tag) آغاز می‌شود که توسط اولین نویسه‌ی @ که خطی را آغاز کند مشخص می‌گردد (با صرف‌نظر از ستاره‌های ابتدایی، فاصله‌ها و جداکننده‌ی آغازین /**). داشتن کامنتی که فقط دارای بخش تگ‌ها و فاقد توضیحات اصلی باشد ممکن است. پس از شروع بخش تگ‌ها، توضیحات اصلی نمی‌تواند ادامه یابد. آرگومان یک تگ می‌تواند در چندین خط گسترش یابد. تعداد تگ‌ها می‌تواند نامحدود باشد، و برخی از انواع تگ‌ها را می‌توان تکرار کرد در حالی که برخی دیگر غیرقابل تکرار هستند. برای نمونه، این تگ @see بخش تگ‌ها را آغاز می‌کند:

/**

 * This sentence holds the main description for this documentation comment.

 * @see java.lang.Object

 */

تگ‌های بلوکی و درون‌خطی (Block and inline Tags)

یک تگ، کلیدواژه‌ای ویژه درون یک کامنت مستندسازی است که توسط دستور javadoc پردازش می‌شود. دو گونه تگ وجود دارد: تگ‌های بلوکی که به صورت تگ @tag ظاهر می‌شوند (همچنین با عنوان تگ‌های مستقل یا standalone شناخته می‌شوند)، و تگ‌های درون‌خطی (inline) که درون آکولادها به شکل تگ {@tag} قرار می‌گیرند. برای اینکه یک تگ بلوکی تفسیر شود، باید در ابتدای خط بیاید، با نادیده گرفتن ستاره‌های ابتدایی، فاصله‌ها و جداکننده (/**). این بدان معناست که می‌توانید از نویسه‌ی @ در جاهای دیگر متن استفاده کنید و به عنوان آغاز یک تگ تفسیر نخواهد شد. اگر می‌خواهید خطی را با نویسه‌ی @ آغاز کنید و نمی‌خواهید به عنوان تگ تفسیر شود، از نهاد HTML با عنوان &#064; استفاده کنید. هر تگ بلوکی دارای متنی مرتبط است که شامل هر متنی پس از تگ تا تگ بعدی یا انتهای کامنت مستندسازی می‌شود (بدون در بر گرفتن خود تگ بعدی). این متن مرتبط می‌تواند در چندین خط گسترش یابد. یک تگ درون‌خطی در هر جایی که متن مجاز باشد، مجاز بوده و تفسیر می‌شود. مثال زیر شامل تگ بلوکی @deprecated و تگ درون‌خطی {@link} است. بخش Javadoc Tags را ببینید.

/**

 * @deprecated  As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}

 */

نوشتن کامنت‌ها در HTML (Write Comments in HTML)

متن باید در قالب HTML به همراه نهادهای HTML و برچسب‌های HTML نوشته شود. می‌توانید از هر نسخه‌ای از HTML که مرورگرتان پشتیبانی می‌کند استفاده کنید. داک‌لت (doclet) استاندارد در جاهای دیگر (خارج از کامنت‌های مستندسازی) کدی منطبق با HTML 3.2 به همراه شیوه‌نامه‌های آبشاری (CSS) و فریم‌ها تولید می‌کند. برای فایل‌های تولیدشده، به دلیل مجموعه‌فریم‌ها (frame sets)، نسخه HTML 4.0 ترجیح داده می‌شود.

برای نمونه، نهادها برای علامت کوچکتری (<) و علامت بزرگتری (>) باید به صورت &lt; و &gt; نوشته شوند. به‌طور مشابه، علامت امپرسند (&) باید به صورت &amp; نوشته شود. برچسب توپر HTML یعنی <b> در مثال زیر نشان داده شده است.

/**

 * This is a <b>doc</b> comment.

 * @see java.lang.Object

 */

ستاره‌های ابتدایی (Leading Asterisks)

هنگامی که دستور javadoc یک کامنت مستندسازی را تجزیه می‌کند، ستاره‌های ابتدایی (*) در هر خط دور ریخته می‌شوند و فاصله‌ها و تب‌های پیش از این ستاره‌های ابتدایی (*) نیز حذف می‌گردند. اگر ستاره‌ی ابتدایی را در یک خط حذف کنید، فاصله‌ی خالی ابتدایی دیگر حذف نمی‌شود؛ در نتیجه می‌توانید نمونه کدهای خود را مستقیماً درون یک برچسب <PRE> در کامنت مستندسازی قرار دهید در حالی که تورفتگی آن حفظ می‌شود. فاصله‌ها توسط مرورگرها نسبت به تب‌ها به شکلی یکدست‌تر تفسیر می‌شوند. تورفتگی نسبت به حاشیه‌ی چپ سنجیده می‌شود (نه نسبت به جداکننده‌ی /** یا برچسب <PRE>).

جمله‌ی نخست (First Sentence)

نخستین جمله‌ی هر کامنت مستندسازی باید یک جمله‌ی خلاصه‌ساز باشد که شامل شرحی مختصر اما کامل از موجودیت اعلان‌شده باشد. این جمله در اولین نقطه‌ای که پس از آن یک فاصله، تب یا پایان‌دهنده‌ی خط قرار گیرد، یا در نخستین تگ بلوکی پایان می‌یابد. دستور javadoc این جمله‌ی نخست را در خلاصه‌ی اعضا (member summary) در بالای صفحه‌ی HTML کپی می‌کند.

اعلان‌های چندفیلدی (Multiple-Field Declarations)

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

/** 

 * The horizontal and vertical distances of point (x,y)

 */

public int x, y;      // Avoid this 

دستور javadoc مستندات زیر را از کد قبلی تولید می‌کند:

public int x

فاصله‌های افقی و عمودی نقطه‌ی (x, y).

public int y

فاصله‌های افقی و عمودی نقطه‌ی (x, y)..PP استفاده از برچسب‌های سربرگ (Header Tags)

هنگام نوشتن کامنت‌های مستندسازی برای اعضا، بهتر است از برچسب‌های سربرگ HTML مانند <H1> و <H2> استفاده نشود، زیرا دستور javadoc یک سند ساختاریافته کامل ایجاد می‌کند و این برچسب‌های ساختاری ممکن است با قالب‌بندی سند تولیدشده تداخل داشته باشند. با این حال، می‌توانید از این سربرگ‌ها در کامنت‌های کلاس و بسته (package) برای ایجاد ساختار مورد نظر خود استفاده کنید.

وراثت کامنت متد (METHOD COMMENT INHERITANCE)

دستور javadoc اجازه وراثت کامنت متد را در کلاس‌ها و رابط‌ها (interfaces) می‌دهد تا متن‌های جاافتاده را پر کند یا به صورت صریح کامنت‌های متد را به ارث ببرد. سازنده‌ها (constructors)، فیلدها و کلاس‌های تو در تو (nested classes) کامنت‌های مستندسازی را به ارث نمی‌برند.

نکته: فایل منبع متدِ به ارث برده‌شده باید در مسیری که توسط گزینه -sourcepath مشخص شده است قرار داشته باشد تا کامنت مستندسازی آن برای کپی کردن در دسترس باشد. نه کلاس و نه بسته آن نیازی به ارسال از طریق خط فرمان ندارند. این رفتار برخلاف نسخه 1.3.n و نسخه‌های پیشین است که در آن‌ها کلاس حتماً باید یک کلاس مستندشده می‌بود.

پر کردن متن جاافتاده

هنگامی که توضیحات اصلی، یا برچسب‌های @return، @param یا @throws در کامنت یک متد وجود نداشته باشند، دستور javadoc توضیحات اصلی یا کامنت برچسب متناظر را از متدی که آن را بازنویسی (override) یا پیاده‌سازی (implement) کرده است (در صورت وجود) کپی می‌کند. بخش «وراثت کامنت متد» (Method Comment Inheritance) را ببینید.

هنگامی که برچسب @param برای یک پارامتر خاص وجود ندارد، کامنت آن پارامتر از متد بالاتر در سلسله‌مراتب وراثت کپی می‌شود. هنگامی که برچسب @throws برای یک استثنای خاص وجود ندارد، برچسب @throws تنها در صورتی کپی می‌شود که آن استثنا اعلان شده باشد.

این رفتار برخلاف نسخه 1.3 و نسخه‌های پیشین است که در آن‌ها وجود هرگونه توضیحات اصلی یا برچسب مانع از به ارث رسیدن تمام کامنت‌ها می‌شد.

بخش «برچسب‌ها و گزینه‌های Javadoc» را ببینید.

وراثت صریح

برچسب درون‌خطی {@inheritDoc} را در توضیحات اصلی متد یا کامنت برچسب‌های @return، @param یا @throws درج کنید. توضیحات اصلی یا کامنت برچسب به ارث رسیده متناظر در همان مکان کپی می‌شود.

وراثت کلاس و رابط (CLASS AND INTERFACE INHERITANCE)

وراثت کامنت در تمام حالت‌های ممکنِ وراثت از کلاس‌ها و رابط‌ها رخ می‌دهد:

•

هنگامی که یک متد در یک کلاس، متدی را در یک سوپرکلاس (superclass) بازنویسی (override) می‌کند

•

هنگامی که یک متد در یک رابط، متدی را در یک رابط والد (superinterface) بازنویسی می‌کند

•

هنگامی که یک متد در یک کلاس، متدی را در یک رابط پیاده‌سازی (implement) می‌کند

در دو حالت نخست، دستور javadoc زیرعنوان Overrides را در مستنداتِ متدِ بازنویسی‌کننده تولید می‌کند. پیوندی به متدی که بازنویسی شده اضافه می‌شود، چه کامنت به ارث برده شده باشد چه نشده باشد.

در حالت سوم، هنگامی که یک متد در یک کلاس مشخص، متدی را در یک رابط پیاده‌سازی می‌کند، دستور javadoc زیرعنوان Specified by را در مستنداتِ متدِ پیاده‌سازی‌کننده تولید می‌کند. پیوندی به متدی که پیاده‌سازی شده قرار می‌گیرد، چه کامنت به ارث برده شده باشد چه نشده باشد.

الگوریتم کامنت‌های متد (METHOD COMMENTS ALGORITHM)

اگر متدی کامنت مستندسازی نداشته باشد، یا شامل برچسب {@inheritDoc} باشد، دستور javadoc از الگوریتم زیر برای یافتن یک کامنت کاربردی استفاده می‌کند. این الگوریتم طوری طراحی شده است که خاص‌ترین کامنت مستندسازیِ قابل‌اعمال را بیابد و رابط‌ها را بر سوپرکلاس‌ها ترجیح دهد:

1.

در هر رابطِ مستقیماً پیاده‌سازی‌شده (یا ارث‌بری‌شده/extended) به ترتیبی که پس از کلمه implements (یا extends) در اعلان متد ظاهر می‌شوند، جستجو کنید. از اولین کامنت مستندسازی یافت‌شده برای این متد استفاده کنید.

2.

اگر مرحله ۱ در یافتن کامنت مستندسازی ناموفق بود، کل این الگوریتم را به صورت بازگشتی بر روی هر رابط مستقیماً پیاده‌سازی‌شده (یا ارث‌بری‌شده) به همان ترتیبی که در مرحله ۱ بررسی شدند، اعمال کنید.

3.

هنگامی که مرحله ۲ در یافتن کامنت مستندسازی ناموفق باشد و این ساختار، کلاسی به غیر از کلاس Object باشد (نه یک رابط):

شرح برچسب‌ها (TAG DESCRIPTIONS)

@author name-text

معرفی‌شده در JDK 1.0

هنگامی که از گزینه -author استفاده می‌شود، یک مدخل «Author» با متن نام مشخص‌شده به اسناد تولیدشده اضافه می‌کند. یک کامنت مستندسازی می‌تواند شامل چندین برچسب @author باشد. شما می‌توانید در هر برچسب @author یک نام، یا در هر برچسب چندین نام را مشخص کنید. در حالت اول، دستور javadoc یک ویرگول (,) و یک فاصله بین نام‌ها درج می‌کند. در حالت دوم، تمام متن بدون تجزیه شدن در سند تولیدشده کپی می‌شود. بنابراین، اگر جداکننده نامِ بومی‌سازی‌شده دیگری به غیر از ویرگول می‌خواهید، می‌توانید از چندین نام در یک خط استفاده کنید. مدخل @author را در How to Write Doc Comments for the Javadoc Tool در http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@author ببینید.

{@code text}

معرفی‌شده در JDK 1.5

معادل با <code>{@literal}</code>.

متن را با قلم کد (code font) بدون تفسیر آن به عنوان نشانه‌گذاری HTML یا برچسب‌های تودرتوی Javadoc نمایش می‌دهد. این امکان را به شما می‌دهد تا به جای موجودیت‌های HTML (&lt; و &gt;)، از براکت‌های شکسته معمولی (< و >) در کامنت‌های مستندسازی استفاده کنید، مانند انواع پارامترها (<Object>)، نابرابری‌ها (3 < 4) یا فلش‌ها (<-). برای مثال، متن کامنت مستندسازی {@code A<B>C} در صفحه HTML تولیدشده بدون تغییر به صورت A<B>C نمایش داده می‌شود. این بدان معنی است که <B> به عنوان پررنگ (bold) تفسیر نمی‌شود و با قلم کد است. اگر همین عملکرد را بدون قلم کد می‌خواهید، از برچسب {@literal} استفاده کنید.

@deprecated deprecated-text

معرفی‌شده در JDK 1.0

یادداشتی اضافه می‌کند که نشان می‌دهد این API دیگر نباید استفاده شود (حتی اگر هنوز کار کند). دستور javadoc متن deprecated-text را به قبل از توضیحات اصلی منتقل کرده، آن را با قلم مورب قرار می‌دهد و پیش از آن هشداری برجسته اضافه می‌کند: Deprecated. این برچسب در تمام کامنت‌های مستندسازی معتبر است: overview، package، class، interface، constructor، method و field.

جمله اولِ متن منسوخ‌شده باید به کاربر بگوید که این API چه زمانی منسوخ شده و از چه چیزی به عنوان جایگزین استفاده کند. دستور javadoc جمله اول را در بخش خلاصه و نمایه (index) کپی می‌کند. جملات بعدی می‌توانند دلیل منسوخ شدن آن را نیز توضیح دهند. شما باید یک برچسب {@link} (برای Javadoc 1.2 یا بالاتر) اضافه کنید که به API جایگزین اشاره داشته باشد.

برای منسوخ کردن یک عنصر برنامه، از برچسب حاشیه‌نویسی @deprecated annotation استفاده کنید. بخش How and When to Deprecate APIs را در http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/deprecation/deprecation.html ببینید.

همچنین @deprecated را در How to Write Doc Comments for the Javadoc Tool در http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@deprecated ببینید.

{@docRoot}

معرفی‌شده در JDK 1.3

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

این برچسب {@docRoot} می‌تواند هم در خط فرمان و هم در کامنت مستندسازی استفاده شود. این برچسب در تمام کامنت‌های مستندسازی معتبر است: overview، package، class، interface، constructor، method و field، و شامل بخش متنی هر برچسبی (مانند برچسب‌های @return، @param و @deprecated) می‌شود.

@exception class-name description

معرفی‌شده در JDK 1.0

کاملاً مشابه برچسب @throws است. مدخل @throws class-name description را ببینید.

{@inheritDoc}

معرفی‌شده در JDK 1.4

مستندات را از نزدیک‌ترین کلاس با قابلیت ارث‌بری یا رابط قابل‌پیاده‌سازی در محل این برچسب به داخل کامنت مستندسازی فعلی به ارث می‌برد (کپی می‌کند). این امکان به شما اجازه می‌دهد تا در سطوح بالاتر درخت وراثت کامنت‌های عمومی‌تری بنویسید و در اطراف متن کپی‌شده توضیحات اختصاصی اضافه کنید.

این برچسب تنها در این مکان‌ها درون یک کامنت مستندسازی معتبر است:

برای شرح نحوه یافتن کامنت‌ها در سلسله‌مراتب وراثت، بخش «وراثت کامنت متد» (Method Comment Inheritance) را ببینید. توجه داشته باشید که اگر این برچسب غایب باشد، کامنت طبق قوانینی که در آن بخش توضیح داده شده است، به طور خودکار به ارث می‌رسد یا به ارث نمی‌رسد.

{@link package.class#member label}

معرفی‌شده در JDK 1.2

یک پیوند درون‌خطی با یک برچسب متنیِ قابل‌مشاهده درج می‌کند که به مستندات بسته، کلاس، یا نام عضو مشخص‌شده از یک کلاس مرجع اشاره دارد. این برچسب در تمام کامنت‌های مستندسازی معتبر است: overview، package، class، interface، constructor، method و field، شامل بخش متنی هر برچسبی مانند برچسب‌های @return، @param و @deprecated. مدخل @link را در How to Write Doc Comments for the Javadoc Tool در http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#{@link ببینید.

این برچسب مشابه برچسب @see است. هر دو برچسب به مراجع یکسانی نیاز دارند و ساختار نگارشی (syntax) یکسانی را برای package.class#member و label می‌پذیرند. تفاوت اصلی در این است که برچسب {@link} به جای قرار دادن پیوند در بخش «همچنین ببینید»، یک پیوند درون‌خطی تولید می‌کند. برچسب {@link} با آکولاد باز و بسته می‌شود تا از بقیه متن درون‌خطی جدا گردد. اگر نیاز دارید در داخل برچسب متنی (label) از آکولاد راست (}) استفاده کنید، از نمایش موجودیت HTML یعنی &#125; استفاده نمایید.

هیچ محدودیتی در تعداد برچسب‌های {@link} مجاز در یک جمله وجود ندارد. شما می‌توانید از این برچسب در بخش توضیحات اصلی هر کامنت مستندسازی یا در بخش متنی هر برچسبی مانند برچسب‌های @deprecated، @return یا @param استفاده کنید.

برای مثال، در اینجا کامنتی آورده شده است که به متد getComponentAt(int, int) ارجاع می‌دهد:

Use the {@link #getComponentAt(int, int) getComponentAt} method.

از این کد، doclet استاندارد کد HTML زیر را تولید می‌کند (با این فرض که به کلاس دیگری در همان بسته ارجاع می‌دهد):

Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.

خط قبلی در صفحه وب به این صورت ظاهر می‌شود:

Use the getComponentAt method.

{@linkplain package.class#member label}

معرفی‌شده در JDK 1.4

همانند برچسب {@link} عمل می‌کند، جز اینکه متن پیوند به جای قلم کد با متن ساده نمایش داده می‌شود. زمانی که برچسب متنی یک متن عادی است، مفید است. برای مثال، Refer to {@linkplain add() the overridden method} به صورت زیر نمایش می‌یابد: Refer to the overridden method.

{@literal text}

معرفی‌شده در JDK 1.5

متن را بدون تفسیر آن به عنوان نشانه‌گذاری HTML یا برچسب‌های تودرتوی Javadoc نمایش می‌دهد. این امکان به شما اجازه می‌دهد تا در کامنت‌های مستندسازی به جای موجودیت‌های HTML (&lt; و &gt;)، از براکت‌های شکسته (< و >) استفاده کنید، مانند انواع پارامترها (<Object>)، نابرابری‌ها (3 < 4) یا فلش‌ها (<-). برای مثال، متن کامنت مستندسازی {@literal A<B>C} در صفحه HTML تولیدشده در مرورگر شما بدون تغییر به صورت A<B>C نمایش می‌یابد. عبارت <B> به عنوان پررنگ (bold) تفسیر نمی‌شود (و با قلم کد نیز نمایش داده نمی‌شود). اگر می‌خواهید همین عملکرد را با متن در قلم کد داشته باشید، از برچسب {@code} استفاده کنید..TP @param parameter-name description معرفی‌شده در JDK 1.0

پارامتری با parameter-name مشخص‌شده به همراه توضیحات تعیین‌شده به بخش Parameters اضافه می‌کند. هنگام نوشتن کامنت مستندسازی، می‌توانید توضیحات را در چندین خط ادامه دهید. این برچسب تنها در کامنت مستندسازی یک متد، سازنده یا کلاس معتبر است. بخش @param را در How to Write Doc Comments for the Javadoc Tool در آدرس http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@param ببینید.

مقدار parameter-name می‌تواند نام یک پارامتر در متد یا سازنده، یا نام یک پارامتر نوع (type parameter) برای یک کلاس، متد، یا سازنده باشد. برای مشخص کردن استفاده از یک پارامتر نوع، از علامت‌های کوچکتری/بزرگتری (< >) در اطراف نام این پارامتر استفاده کنید.

مثالی از پارامتر نوع برای یک کلاس:

/**

 * @param <E> Type of element stored in a list

 */

public interface List<E> extends Collection<E> {

}

مثالی از پارامتر نوع برای یک متد:

/**

 * @param string  the string to be converted

 * @param type    the type to convert the string to

 * @param <T>     the type of the element

 * @param <V>     the value of the element

 */

<T, V extends T> V convert(String string, Class<T> type) {

}

@return description

معرفی‌شده در JDK 1.0

بخشی با عنوان Returns به همراه متن توضیحات اضافه می‌کند. این متن باید نوع بازگشتی و محدوده مجاز مقادیر را شرح دهد. این برچسب تنها در کامنت مستندسازی یک متد معتبر است. بخش @return را در How to Write Doc Comments for the Javadoc Tool در آدرس http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@return ببینید.

@see reference

معرفی‌شده در JDK 1.0

یک عنوان See Also به همراه پیوند یا مدخل متنی که به یک مرجع اشاره دارد، اضافه می‌کند. یک کامنت مستندسازی می‌تواند شامل هر تعداد برچسب @see باشد که همگی ذیل یک عنوان گروه‌بندی می‌شوند. برچسب @see دارای سه حالت مختلف است. این فرم رایج‌ترین حالت است. این برچسب در هر کامنت مستندسازی معتبر است: مرور کلی (overview)، بسته، کلاس، رابط، سازنده، متد یا فیلد. برای قرار دادن یک پیوند درون‌خطی در یک جمله به یک بسته، کلاس یا عضو، {@link} را ببینید.

فرم ۱. فرم برچسب @see string یک مدخل متنی برای string اضافه می‌کند. هیچ پیوندی تولید نمی‌شود. این رشته نشان‌دهنده یک کتاب یا مرجع دیگری برای اطلاعاتی است که از طریق URL در دسترس نیست. دستور javadoc این حالت را با جستجوی یک علامت نقل‌قول جفتی (") به عنوان نویسه اول، از موارد پیشین تشخیص می‌دهد. برای مثال، @see "The Java Programming Language" که متن زیر را تولید می‌کند:

See Also:

"The Java Programming Language"

فرم ۲. فرم @see <a href="URL#value">label</a> پیوندی را به صورت تعریف‌شده توسط URL#value اضافه می‌کند. پارامتر URL#value یک URL نسبی یا مطلق است. دستور javadoc این حالت را با جستجوی نماد کوچکتری (<) به عنوان نویسه اول، از سایر موارد تشخیص می‌دهد. برای مثال، @see <a href="spec.html#section">Java Spec</a> پیوند زیر را تولید می‌کند:

See Also:

Java Spec

فرم ۳. فرم @see package.class#member label پیوندی را به همراه یک برچسب متنی قابل‌مشاهده اضافه می‌کند که به مستندات نام مشخص‌شده و ارجاع‌یافته در زبان Java اشاره دارد. برچسب (label) اختیاری است. در صورت حذف برچسب، نام به جای آن به صورت متنی قابل‌مشاهده و به طور مناسب کوتاه‌شده نمایش داده می‌شود. از گزینه -noqualifier برای حذف سراسری نام بسته از این متن قابل‌مشاهده استفاده کنید. زمانی از برچسب استفاده کنید که می‌خواهید متن قابل‌مشاهده با متنِ تولیدشده به صورت خودکار متفاوت باشد. بخش How a Name Appears را ببینید.

تنها در Java SE 1.2، نام (و نه برچسب) به طور خودکار درون برچسب‌های HTML <code> قرار می‌گیرد. با شروع از Java SE 1.2.2، برچسب <code> همیشه در اطراف متن قابل‌مشاهده قرار می‌گیرد، خواه از برچسب استفاده شده باشد یا نه.

در مثال زیر، یک برچسب @see (در کلاس Character) به متد equals در کلاس String ارجاع می‌دهد. این برچسب شامل هر دو آرگومان است: نام String#equals(Object) و برچسب equals.

/**

 * @see String#equals(Object) equals

 */

داکلت استاندارد HTML مشابه زیر را تولید می‌کند:

<dl>

<dt><b>See Also:</b>

<dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a>

</dl>

کد پیشین در یک مرورگر مشابه زیر خواهد بود، جایی که برچسب متن پیوند قابل‌مشاهده است:

See Also:

equals

مشخص کردن نام (Specify a Name)

این نام package.class#member می‌تواند کاملاً مقید باشد، مانند java.lang.String#toUpperCase() یا غیرمقید باشد، مانند String#toUpperCase() یا #toUpperCase(). اگر نام کمتر از حالت کامل مقید باشد، دستور javadoc از ترتیب جستجوی استاندارد کامپایلر Java برای یافتن آن استفاده می‌کند. بخش Search Order for the @see Tag را ببینید. نام می‌تواند حاوی فاصله سفید در داخل پرانتزها باشد، مانند بین آرگومان‌های متد. مزیت ارائه نام‌های کوتاه‌تر و تا حدی مقید این است که تایپ آنها کوتاه‌تر بوده و آشفتگی کمتری در کد منبع وجود دارد. فهرست زیر فرم‌های مختلف نام را نشان می‌دهد که در آن Class می‌تواند یک کلاس یا رابط باشد؛ Type می‌تواند یک کلاس، رابط، آرایه یا نوع اولیه (primitive) باشد؛ و method می‌تواند یک متد یا سازنده باشد.

فرم‌های رایج برای @see package.class#member

ارجاع به عضوی از کلاس جاری

@see #field

@see #method(Type, Type,...)

@see #method(Type argname, Type argname,...)

@see #constructor(Type, Type,...)

@see #constructor(Type argname, Type argname,...) 

ارجاع به کلاسی دیگر در بسته‌های جاری یا واردشده

@see Class#field

@see Class#method(Type, Type,...)

@see Class#method(Type argname, Type argname,...)

@see Class#constructor(Type, Type,...)

@see Class#constructor(Type argname, Type argname,...)

@see Class.NestedClass

@see Class 

ارجاع به عنصری در بسته‌ای دیگر (کاملاً مقید)

@see package.Class#field

@see package.Class#method(Type, Type,...)

@see package.Class#method(Type argname, Type argname,...)

@see package.Class#constructor(Type, Type,...)

@see package.Class#constructor(Type argname, Type argname,...)

@see package.Class.NestedClass

@see package.Class

@see package

نکاتی درباره فهرست پیشین:.TP 0.2i • مجموعه اول از ساختارها بدون کلاس یا بسته، باعث می‌شود دستور javadoc تنها در سلسله‌مراتب کلاس فعلی جستجو کند. این دستور عضوی از کلاس یا رابط فعلی، یکی از ابرکلاس‌ها یا ابررابط‌های آن، یا یکی از کلاس‌ها یا رابط‌های دربرگیرنده آن را پیدا می‌کند (موارد جستجوی ۱–۳). این حالت سایر بخش‌های بسته فعلی یا بسته‌های دیگر را جستجو نمی‌کند (موارد جستجوی ۴–۵). بخش «ترتیب جستجو برای برچسب @see» را ببینید.

•

اگر هر متد یا سازنده‌ای به‌صورت یک نام بدون پرانتز وارد شود، مانند getValue، و فیلدی با همان نام وجود نداشته باشد، دستور javadoc همچنان پیوندی به آن متد ایجاد می‌کند. اگر این متد سربارگذاری شده باشد (overloaded)، دستور javadoc به نخستین متدی که در جستجوی خود با آن مواجه شود پیوند می‌دهد، که نامعین است.

•

کلاس‌های تودرتو (nested classes) باید برای همه فرم‌ها به‌صورت outer.inner مشخص شوند، نه صرفاً به‌صورت inner.

•

همان‌طور که بیان شد، علامت هش (#) به جای نقطه (.) یک عضو را از کلاسش جدا می‌کند. این امر دستور javadoc را قادر می‌سازد تا ابهامات را برطرف کند، چرا که نقطه برای جداسازی کلاس‌ها، کلاس‌های تودرتو، بسته‌ها و زیربسته‌ها نیز به کار می‌رود. با این حال، دستور javadoc در صورت نبود ابهام، نقطه را به درستی تجزیه می‌کند، اما یک هشدار جهت آگاهی شما چاپ می‌کند.

ترتیب جستجو برای برچسب @see

دستور javadoc برچسب @see را که در یک فایل مبدأ، فایل بسته یا فایل مروری ظاهر می‌شود، پردازش می‌کند. در دو فایل آخر، باید نامی را که همراه با برچسب @see ارائه می‌دهید، به‌طور کامل واجد شرایط (fully qualified) کنید. در یک فایل مبدأ، می‌توانید نامی را مشخص کنید که به‌صورت کامل یا جزئی واجد شرایط (fully qualified یا partially qualified) باشد.

در ادامه، ترتیب جستجو برای برچسب @see آمده است.

1.

کلاس یا رابط فعلی.

2.

هر یک از کلاس‌ها و رابط‌های دربرگیرنده، با جستجوی نزدیک‌ترین آن‌ها در ابتدا.

3.

هر یک از ابرکلاس‌ها و ابررابط‌ها، با جستجوی نزدیک‌ترین آن‌ها در ابتدا.

4.

بسته فعلی.

5.

هر یک از بسته‌ها، کلاس‌ها و رابط‌های واردشده (imported)، با جستجو به ترتیبی که در عبارت‌های import آمده‌اند.

دستور javadoc برای هر کلاسی که با آن مواجه می‌شود، جستجو را به‌صورت بازگشتی در موارد ۱ تا ۳ ادامه می‌دهد تا زمانی که یک تطابق پیدا کند. بدین معنا که پس از جستجو در کلاس فعلی و کلاس دربرگیرنده آن E، پیش از کلاس‌های دربرگیرنده E، در ابرکلاس‌های E جستجو می‌کند. در موارد ۴ و ۵، دستور javadoc کلاس‌ها یا رابط‌های درون یک بسته را با ترتیب مشخصی جستجو نمی‌کند (این ترتیب به کامپایلر بستگی دارد). در مورد ۵، دستور javadoc در java.lang جستجو می‌کند زیرا توسط تمام برنامه‌ها وارد شده است.

هنگامی که دستور javadoc در یک فایل مبدأ با برچسب @see مواجه می‌شود که نام آن به‌طور کامل واجد شرایط نشده است، نام مشخص‌شده را با همان ترتیبی جستجو می‌کند که کامپایلر جاوا جستجو می‌کند؛ با این تفاوت که دستور javadoc برخی از ابهامات فضای نام را تشخیص نمی‌دهد زیرا فرض می‌کند کد مبدأ عاری از این خطاهاست. این ترتیب جستجو به‌طور رسمی در «مشخصات زبان جاوا» (Java Language Specification) تعریف شده است. دستور javadoc آن نام را در تمامی کلاس‌ها و بسته‌های مرتبط و واردشده جستجو می‌کند. به‌ویژه، با این ترتیب جستجو می‌کند:

1.

کلاس یا رابط فعلی.

2.

هر یک از کلاس‌ها و رابط‌های دربرگیرنده، با جستجوی نزدیک‌ترین آن‌ها در ابتدا.

3.

هر یک از ابرکلاس‌ها و ابررابط‌ها، با جستجوی نزدیک‌ترین آن‌ها در ابتدا.

4.

بسته فعلی.

5.

هر یک از بسته‌ها، کلاس‌ها و رابط‌های واردشده، با جستجو به ترتیبی که در عبارت‌های import آمده‌اند.

دستور javadoc لزوماً در زیرکلاس‌ها جستجو نمی‌کند، و در بسته‌های دیگر نیز جستجو نخواهد کرد، حتی اگر مستندات آن‌ها در همان نوبت اجرا تولید شود. برای مثال، اگر برچسب @see در کلاس java.awt.event.KeyEvent باشد و به نامی در بسته java.awt package اشاره کند، دستور javadoc در آن بسته جستجو نخواهد کرد مگر اینکه آن کلاس آن را وارد (import) کرده باشد.

نحوه نمایش نام

اگر label حذف شود، عبارت package.class.member نمایش داده می‌شود. به‌طور کلی، نسبت به کلاس و بسته فعلی به‌طور مناسبی کوتاه می‌شود. کوتاه شدن به این معناست که دستور javadoc تنها حداقل نام مورد نیاز را نمایش می‌دهد. برای مثال، اگر متد String.toUpperCase() شامل ارجاعاتی به عضوی از همان کلاس و عضوی از یک کلاس دیگر باشد، نام کلاس تنها در مورد دوم نمایش داده می‌شود، همان‌طور که در فهرست زیر نشان داده شده است. از گزینه -noqualifier برای حذف سراسری نام بسته‌ها استفاده کنید.

نوع ارجاع: برچسب @see به عضوی از همان کلاس در همان بسته اشاره دارد
مثال در: @see String#toLowerCase()
نمایش به‌صورت: toLowerCase() - نام‌های بسته و کلاس حذف می‌شوند

نوع ارجاع: برچسب @see به عضوی از کلاسی دیگر در همان بسته اشاره دارد
مثال در: @see Character#toLowerCase(char)
نمایش به‌صورت: Character.toLowerCase(char) - نام بسته حذف می‌شود، نام کلاس درج می‌شود

نوع ارجاع: برچسب @see به عضوی از کلاسی دیگر در بسته‌ای دیگر اشاره دارد
مثال در: @see java.io.File#exists()
نمایش به‌صورت: java.io.File.exists() - نام‌های بسته و کلاس درج می‌شوند

مثال‌هایی از برچسب @see

توضیحات سمت راست نشان می‌دهند که نام چگونه ظاهر می‌شود هنگامی که برچسب @see در کلاسی در بسته‌ای دیگر قرار دارد، مانند java.applet.Applet. بخش @see را در «نحوه نگارش توضیحات مستندسازی برای ابزار Javadoc» در http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@see ببینید.

                                            See also:

@see java.lang.String                   //  String                           

@see java.lang.String The String class  //  The String class                 

@see String                             //  String                           

@see String#equals(Object)              //  String.equals(Object)            

@see String#equals                      //  String.equals(java.lang.Object)   

@see java.lang.Object#wait(long)        //  java.lang.Object.wait(long)      

@see Character#MAX_RADIX                //  Character.MAX_RADIX              

@see <a href="spec.html">Java Spec</a>  //  Java Spec            

@see "The Java Programming Language"    //  "The Java Programming Language" 

نکته: می‌توانید برچسب @see را گسترش دهید تا با استفاده از گزینه -link به کلاس‌هایی که مستندسازی نمی‌شوند پیوند برقرار کنید.

@serial field-description | include | exclude

معرفی‌شده در JDK 1.2

در توضیحات مستندسازی برای یک فیلد پیش‌فرضِ قابل‌سریال‌سازی (serializable) به کار می‌رود. بخش «مستندسازی فیلدها و داده‌های قابل‌سریال‌سازی برای یک کلاس» را در http://docs.oracle.com/javase/8/docs/platform/serialization/spec/serial-arch.html#5251 ببینید.

همچنین بخش «معیارهای اوراکل برای گنجاندن کلاس‌ها در مشخصات فرم سریال‌سازی‌شده» را در http://www.oracle.com/technetwork/java/javase/documentation/serialized-criteria-137781.html ببینید.

یک field-description اختیاری باید معنای فیلد را توضیح دهد و مقادیر مجاز را فهرست کند. در صورت نیاز، توضیحات می‌تواند چندین خط را در بر بگیرد. داکلت استاندارد (standard doclet) این اطلاعات را به صفحه فرم سریال‌سازی‌شده اضافه می‌کند. بخش «صفحات ارجاع متقابل» (Cross-Reference Pages) را ببینید.

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

آرگومان‌های include و exclude مشخص می‌کنند که آیا یک کلاس یا بسته باید در صفحه فرم سریال‌سازی‌شده گنجانده شود یا کنار گذاشته شود. عملکرد آن‌ها به این صورت است:

برای مثال، بسته javax.swing در package.html یا package-info.java با برچسب @serialexclude علامت‌گذاری شده است. کلاس عمومی java.security.BasicPermission با برچسب @serial exclude علامت‌گذاری شده است. کلاس سطح بسته java.util.PropertyPermissionCollection با برچسب @serial include علامت‌گذاری شده است.

برچسب @serial در سطح کلاس، برچسب @serial در سطح بسته را بازنویسی (override) می‌کند.

@serialData data-description

معرفی‌شده در JDK 1.2

از مقدار شرح داده (data description) برای مستندسازی انواع و ترتیب داده‌ها در فرم سریال‌سازی‌شده استفاده می‌کند. این داده‌ها شامل داده‌های اختیاری نوشته‌شده توسط متد writeObject و تمام داده‌های (از جمله کلاس‌های پایه) نوشته‌شده توسط متد Externalizable.writeExternal می‌شود.

برچسب @serialData می‌تواند در توضیحات مستندسازی برای متدهای writeObject، readObject، writeExternal، readExternal، writeReplace و readResolve استفاده شود.

@serialField field-namefield-typefield-description

معرفی‌شده در JDK 1.2

یک مؤلفه ObjectStreamField از عضو serialPersistentFields یک کلاس Serializable را مستند می‌کند. برای هر مؤلفه ObjectStreamField از یک برچسب @serialField استفاده کنید.

@since since-text

معرفی‌شده در JDK 1.1

یک عنوان Since با مقدار مشخص‌شده در since-text به مستندات تولیدشده اضافه می‌کند. این متن ساختار داخلی خاصی ندارد. این برچسب در هرگونه توضیحات مستندسازی معتبر است: بررسی اجمالی (overview)، بسته، کلاس، رابط، سازنده، متد یا فیلد. این برچسب بدین معناست که این تغییر یا ویژگی از زمان انتشار نرم‌افزاری که با مقدار since-text مشخص شده وجود داشته است، برای مثال: @since 1.5.

برای کد مبدأ پلتفرم جاوا، برچسب @since نشان‌دهنده نسخه مشخصات API پلتفرم جاوا است، که لزوماً زمان اضافه شدن کد مبدأ به پیاده‌سازی مرجع نیست. استفاده از چند برچسب @since مجاز است و مشابه چند برچسب @author با آن‌ها رفتار می‌شود. در صورتی که عنصر برنامه توسط بیش از یک API استفاده شده باشد، می‌توانید از چندین برچسب استفاده کنید.

@throws class-namedescription

معرفی‌شده در JDK 1.2

مشابه برچسب @exception عمل می‌کند. بخش @throws را در «نحوه نگارش توضیحات مستندسازی برای ابزار Javadoc» در http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@exception ببینید.

برچسب @throws یک زیرعنوان Throws را همراه با متن‌های class-name و description به مستندات تولیدشده اضافه می‌کند. مقدار class-name نام استثنایی است که ممکن است توسط متد پرتاب شود. این برچسب تنها در توضیحات مستندسازیِ یک متد یا سازنده معتبر است. اگر این کلاس به‌طور کامل مشخص نشده باشد، دستور javadoc از ترتیب جستجو برای یافتن این کلاس استفاده می‌کند. می‌توان از چندین برچسب @throws در یک توضیح مستندسازیِ مشخص برای استثناهای یکسان یا متفاوت استفاده کرد. بخش «ترتیب جستجو برای برچسب @see» را ببینید.

برای اطمینان از اینکه تمامی استثناهای بررسی‌شده (checked exceptions) مستند شده‌اند، زمانی که برچسب @throws برای یک استثنا در عبارت throws وجود نداشته باشد، دستور javadoc آن استثنا را (بدون شرح) به خروجی HTML اضافه می‌کند، گویی که با برچسب @throws مستندسازی شده باشد.

مستندات @throws تنها زمانی از یک متد بازنویسی‌شده (overridden) به یک زیرکلاس کپی می‌شود که استثنا به‌طور صریح در متد بازنویسی‌شده اعلان شده باشد. همین امر برای کپی کردن از متد یک رابط به متد پیاده‌سازی‌کننده نیز صدق می‌کند. می‌توانید از برچسب {@inheritDoc} برای وادار کردن برچسب @throws به ارث‌بری مستندات استفاده کنید.

{@value package.class#field}

معرفی‌شده در JDK 1.4

مقادیر ثابت را نمایش می‌دهد. هنگامی که برچسب {@value} بدون آرگومان در توضیحات مستندسازیِ یک فیلد ایستا (static) استفاده شود، مقدار آن ثابت را نمایش می‌دهد:

/**

 * The value of this constant is {@value}.

 */

public static final String SCRIPT_START = "<script>"

هنگامی که با آرگومان package.class#field در هر توضیح مستندسازی استفاده شود، برچسب {@value} مقدار ثابت مشخص‌شده را نمایش می‌دهد:

/**

 * Evaluates the script starting with {@value #SCRIPT_START}.

 */

public String evalScript(String script) {}

آرگومان package.class#field شکلی مشابه با آرگومان برچسب @see به خود می‌گیرد، با این تفاوت که عضو مربوطه باید یک فیلد ایستا باشد.

مقادیر این ثابت‌ها همچنین در بخش Constant Field Values در http://docs.oracle.com/javase/8/docs/api/constant-values.html نمایش داده می‌شوند..TP @version version-text در JDK 1.0 معرفی شد.

هنگامی که از گزینهٔ -version استفاده شود، یک زیرعنوان Version با مقدار مشخص‌شدهٔ version-text به اسناد تولیدشده اضافه می‌کند. این برچسب برای نگهداری شمارهٔ انتشار فعلی نرم‌افزاری که این کد بخشی از آن است در نظر گرفته شده است، برخلاف برچسب @since که شمارهٔ انتشاری را نگه می‌دارد که این کد در آن معرفی شده بود. مقدار version-text ساختار داخلی خاصی ندارد. بخش @version را در «How to Write Doc Comments for the Javadoc Tool» در http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@version ببینید.

یک کامنت مستندسازی می‌تواند شامل چند برچسب @version باشد. در صورت لزوم، می‌توانید برای هر برچسب @version یک شمارهٔ انتشار یا برای هر برچسب چند شمارهٔ انتشار مشخص کنید. در حالت اول، دستور javadoc یک کاما (,) و یک فاصله بین نام‌ها درج می‌کند. در حالت دوم، کل متن بدون تجزیه شدن در سند تولیدشده کپی می‌شود. بنابراین، هنگامی که می‌خواهید جداکننده‌ای بومی‌سازی‌شده به‌جز کاما داشته باشید، می‌توانید چندین نام را در هر خط استفاده کنید.

برچسب‌های نمای کلی (OVERVIEW TAGS)

برچسب‌های نمای کلی برچسب‌هایی هستند که می‌توانند در کامنت مستندسازیِ صفحهٔ مرور کلی ظاهر شوند (که معمولاً در فایل منبعی با نام overview.html قرار دارد). مشابه هر کامنت مستندسازی دیگر، این برچسب‌ها باید پس از توضیحات اصلی قرار گیرند.

نکته: برچسب {@link} در اسناد نمای کلی در Java SE 1.2 دارای باگ است. متن به‌درستی ظاهر می‌شود اما پیوندی ندارد. برچسب {@docRoot} در حال حاضر در اسناد نمای کلی کار نمی‌کند.

برچسب‌های نمای کلی به شرح زیر هستند:

@see reference || @since since-text || @serialField field-name field-type field-description || @author name-text || @version version-text || {@link package.class#member label} || {@linkplain package.class#member label} || {@docRoot} ||

برچسب‌های بسته (PACKAGE TAGS)

برچسب‌های بسته برچسب‌هایی هستند که می‌توانند در کامنت مستندسازی برای یک بسته ظاهر شوند، که در فایل منبع با نام package.html یا package-info.java قرار دارد. برچسب @serial در اینجا تنها با آرگومان include یا exclude قابل استفاده است.

برچسب‌های بسته به شرح زیر هستند:

@see reference || @since since-text || @serial field-description | include | exclude || @author name-text || @version version-text || {@linkplain package.class#member label} || {@linkplain package.class#member label} || {@docRoot} ||

برچسب‌های کلاس و واسط (CLASS AND INTERFACE TAGS)

موارد زیر برچسب‌هایی هستند که می‌توانند در کامنت مستندسازی برای یک کلاس یا واسط ظاهر شوند. برچسب @serial درون مستندات یک کلاس یا واسط تنها با یک آرگومان include یا exclude قابل استفاده است.

@see reference || @since since-text || @deprecated deprecated-text || @serial field-description | include | exclude || @author name-text || @version version-text || {@link package.class#member label} || {@linkplain package.class#member label} || {@docRoot} ||

مثال کامنت کلاس:

/**

 * A class representing a window on the screen.

 * For example:

 * <pre>

 *    Window win = new Window(parent);

 *    win.show();

 * </pre>

 *

 * @author  Sami Shaio

 * @version 1.13, 06/08/06

 * @see     java.awt.BaseWindow

 * @see     java.awt.Button

 */

class Window extends BaseWindow {

   ...

}

برچسب‌های فیلد (FIELD TAGS)

این برچسب‌ها می‌توانند در فیلدها ظاهر شوند:

@see reference || @since since-text || @deprecated deprecated-text || @serial field-description | include | exclude || @serialField field-name field-type field-description || {@link package.class#member label} || {@linkplain package.class#member label} || {@docRoot} || {@value package.class#field}

مثال کامنت فیلد:

    /**

     * The X-coordinate of the component.

     *

     * @see #getLocation()

     */

    int x = 1263732;

برچسب‌های سازنده و متد (CONSTRUCTOR AND METHOD TAGS)

برچسب‌های زیر می‌توانند در کامنت مستندسازی برای یک سازنده یا یک متد ظاهر شوند، به‌جز برچسب @return که نمی‌تواند در یک سازنده ظاهر شود، و برچسب {@inheritDoc} که دارای محدودیت‌هایی است.

@see reference || @since since-text || @deprecated deprecated-text || @param parameter-name description || @return description || @throws class-name description || @exception class-name description || @serialData data-description || {@link package.class#member label} || {@linkplain package.class#member label} || {@inheritDoc} || {@docRoot}

نکته: برچسب @serialData تنها می‌تواند در کامنت مستندسازی برای متدهای writeObject، readObject، writeExternal، readExternal، writeReplace و readResolve استفاده شود.

مثال کامنت متد:

/**

     * Returns the character at the specified index. An index 

     * ranges from <code>0</code> to <code>length() - 1</code>

     *

     * @param     index the index of the desired character.

     * @return    the desired character.

     * @exception StringIndexOutOfRangeException 

     *              if the index is not in the range <code>0</code> 

     *              to <code>length()-1</code>

     * @see       java.lang.Character#charValue()

     */

    public char charAt(int index) {

       ...

    }

•

همچنین ببینید: گزینه‌های Javadoc

•

همچنین ببینید: گزینه‌های داکلت استاندارد

گزینه‌ها عبارتند از:

-1.1 || -author || -bootclasspath classpathlist || -bottom text || -breakiterator || -charset name || -classpath classpathlist || -d directory || -docencoding name || -docfilesubdirs || -doclet class || -docletpath classpathlist || -doctitle title || -encoding || -exclude packagename1:packagename2:... || -excludedocfilessubdir name1:name2 || -extdirs dirist || -footer footer || -group groupheading packagepattern:packagepattern || -header header || -help || -helpfile path\filename || -Jflag || -javafx ||-keywords || -link extdocURL || -linkoffline extdocURL packagelistLoc || -linksource || -locale language_country_variant || -nocomment || -nodeprecated || -nodeprecatedlist || -nohelp || -noindex || -nonavbar || -noqualifier all | packagename1:packagename2... || -nosince || -notimestamp || -notree || -overview path/filename || -package || -private || -protected || -public || -quiet || -serialwarn || -source release || -sourcepath sourcepathlist || -sourcetab tablength || -splitindex || -stylesheet path/filename || -subpackages package1:package2:... || -tag tagname:Xaoptcmf:"taghead" || -taglet class || -tagletpath tagletpathlist || -title title || -top || -use || -verbose || -version || -windowtitle title

گزینه‌های زیر، گزینه‌های اصلی Javadoc هستند که برای تمام داکلت‌ها در دسترس می‌باشند. داکلت استاندارد باقی موارد را ارائه می‌دهد: -bootclasspath، -breakiterator، -classpath، -doclet، -docletpath، -encoding، -exclude، -extdirs، -help، -locale، -overview، -package، -private، -protected، -public، -quiet، -source، -sourcepath، -subpackages و -verbose.

گزینه‌های JAVADOC (JAVADOC OPTIONS)

-overview path/filename

مشخص می‌کند که دستور javadoc باید متن مستندات کلی (overview) را از فایل مبدأ مشخص‌شده توسط path/filename واکشی کرده و آن را در صفحهٔ Overview (فایل overview-summary.html) قرار دهد. مسیر path/filename نسبت به دایرکتوری جاری سنجیده می‌شود.

اگرچه می‌توانید از هر نام دلخواهی برای مقدار filename استفاده کنید و آن را در هر کجای مسیر قرار دهید، اما معمول است که نام آن را overview.html بگذارید و آن را در درخت مبدأ درون دایرکتوری‌ای قرار دهید که شامل بالاترین دایرکتوری‌های بسته است. در این مکان، هنگام مستندسازی بسته‌ها به هیچ مسیری نیاز نیست، زیرا گزینهٔ -sourcepath به این فایل اشاره می‌کند.

برای مثال، اگر درخت مبدأ برای بستهٔ java.lang برابر با /src/classes/java/lang/ باشد، می‌توانید فایل overview را در /src/classes/overview.html قرار دهید.

بخش Real-World Examples را ببینید.

برای اطلاعات دربارهٔ فایل مشخص‌شده با path/filename، بخش Overview Comment Files را ببینید.

صفحهٔ overview تنها زمانی ایجاد می‌شود که دو یا چند نام بسته را به دستور javadoc ارسال کنید. برای توضیحات بیشتر، بخش HTML Frames را ببینید. عنوان صفحهٔ overview توسط -doctitle تنظیم می‌شود.

-Xdoclint:(all|none|[-]<group>)

هشدارهایی را برای ارجاعات نادرست، عدم دسترس‌پذیری (accessibility) و کامنت‌های مفقود Javadoc گزارش می‌کند، و خطاهایی را برای نحو (syntax) نامعتبر Javadoc و برچسب‌های مفقود HTML گزارش می‌دهد.

این گزینه به دستور javadoc امکان می‌دهد تمام کامنت‌های مستنداتی گنجانده‌شده در خروجی تولیدشده را بررسی کند. طبق معمول، می‌توانید با گزینه‌های استاندارد -public، -protected، -package و -private مواردی را که باید در خروجی تولیدشده قرار گیرند انتخاب کنید.

هنگامی که -Xdoclint فعال باشد، مشکلات را با پیام‌هایی مشابه با دستور javac گزارش می‌دهد. دستور javadoc یک پیام، رونوشتی از خط مبدأ و یک علامت هشتک (caret) چاپ می‌کند که به موقعیت دقیق خطای شناسایی‌شده اشاره دارد. پیام‌ها بسته به شدت مشکل و احتمال ایجاد خطا در صورت اعتبارسنجی مستندات تولیدشده توسط یک validator، ممکن است هشدار یا خطا باشند. برای نمونه، ارجاعات نادرست یا کامنت‌های مفقود Javadoc باعث نمی‌شوند که دستور javadoc کدهای HTML نامعتبر تولید کند، بنابراین این موارد به عنوان هشدار گزارش می‌شوند. خطاهای نحوی یا برچسب‌های پایانی مفقود در HTML باعث می‌شوند که دستور javadoc خروجی نامعتبر تولید کند، بنابراین این موارد به عنوان خطا گزارش می‌شوند.

به‌طور پیش‌فرض، گزینهٔ -Xdoclint فعال است. آن را با گزینهٔ -Xdoclint:none غیرفعال کنید.

آنچه را که گزینهٔ -Xdoclint گزارش می‌دهد با گزینه‌های زیر تغییر دهید:

متغیر group یکی از مقادیر زیر را می‌پذیرد:

می‌توانید گزینهٔ -Xdoclint را چندین بار مشخص کنید تا بررسی خطاها و هشدارها در چند دسته فعال شود. همچنین، می‌توانید چندین دستهٔ خطا و هشدار را با استفاده از گزینه‌های پیش‌گفته مشخص کنید. برای مثال، از هر یک از دستورهای زیر برای بررسی مشکلات HTML، نحو و دسترس‌پذیری در فایل filename استفاده کنید.

javadoc -Xdoclint:html -Xdoclint:syntax -Xdoclint:accessibility filename

javadoc -Xdoclint:html,syntax,accessibility filename

نکته: دستور javadoc جامعیت این بررسی‌ها را تضمین نمی‌کند. به‌ویژه، این ابزار یک بررسی‌کنندهٔ کامل تطابق با HTML نیست. هدف گزینهٔ -Xdoclint این است که دستور javadoc را قادر سازد بخش عمده‌ای از خطاهای رایج را گزارش کند.

دستور javadoc تلاشی برای اصلاح ورودی نامعتبر نمی‌کند، بلکه صرفاً آن را گزارش می‌دهد.

-public

تنها کلاس‌ها و اعضای public را نشان می‌دهد.

-protected

تنها کلاس‌ها و اعضای protected و public را نشان می‌دهد. این حالت پیش‌فرض است.

-package

تنها کلاس‌ها و اعضای package، protected و public را نشان می‌دهد.

-private

تمام کلاس‌ها و اعضا را نشان می‌دهد.

-help

راهنمای برخط را نمایش می‌دهد که تمام گزینه‌های خط فرمان javadoc و doclet را فهرست می‌کند.

-doclet class

فایل کلاسی را مشخص می‌کند که داکلتِ مورد استفاده در تولید مستندات را راه‌اندازی می‌کند. از نام کاملاً مشخص (fully qualified name) استفاده کنید. این داکلت محتوا را تعیین کرده و خروجی را قالب‌بندی می‌کند. اگر از گزینهٔ -doclet استفاده نشود، دستور javadoc از داکلت استاندارد برای تولید قالب پیش‌فرض HTML استفاده می‌کند. این کلاس باید شامل متد start(Root) باشد. مسیر رسیدن به این کلاس آغازین توسط گزینهٔ -docletpath تعیین می‌شود. بخش Doclet Overview را در http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/overview.html ببینید.

-docletpath classpathlist

مسیر فایل کلاس آغازین داکلت (مشخص‌شده با گزینهٔ -doclet) و هر فایل JAR که به آن وابسته است را مشخص می‌کند. اگر فایل کلاس آغازین درون یک فایل JAR باشد، این گزینه مسیر منتهی به آن فایل JAR را مشخص می‌کند. می‌توانید یک مسیر مطلق یا مسیری نسبت به دایرکتوری جاری مشخص کنید. اگر classpathlist شامل چندین مسیر یا فایل JAR باشد، باید آن‌ها را در Oracle Solaris با دونقطه (:) و در Windows با نقطه‌ویرگول (;) از یکدیگر جدا کرد. زمانی که کلاس آغازین داکلت از قبل در مسیر جست‌وجو قرار داشته باشد، نیازی به این گزینه نیست. بخش Doclet Overview را در http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/overview.html ببینید.

-1.1

از Javadoc 1.4 بدون هیچ جایگزینی حذف شده است. این گزینه مستنداتی با ظاهر و قابلیت‌های مستندات تولیدشده توسط Javadoc 1.1 ایجاد می‌کرد (این گزینه هرگز از کلاس‌های تودرتو پشتیبانی نکرد). اگر به این گزینه نیاز دارید، به جای آن از Javadoc 1.2 یا 1.3 استفاده کنید.

-source release

نسخهٔ کد منبع پذیرفته‌شده را مشخص می‌کند. مقادیر زیر برای پارامتر release مجاز هستند. از مقدار release متناظر با مقداری که هنگام کامپایل کد با دستور javac استفاده می‌کنید بهره ببرید.

-sourcepath sourcepathlist

مسیرهای جست‌وجو را برای یافتن فایل‌های مبدأ هنگام ارسال نام بسته‌ها یا گزینهٔ -subpackages به دستور javadoc مشخص می‌کند. چندین مسیر را با دونقطه (:) از یکدیگر جدا کنید. دستور javadoc تمام زیردایرکتوری‌های مسیرهای مشخص‌شده را جست‌وجو می‌کند. توجه داشته باشید که این گزینه نه تنها برای یافتن محل فایل‌های مبدأ در حال مستندسازی، بلکه برای یافتن فایل‌های مبدأیی که مستندسازی نمی‌شوند اما کامنت‌های آن‌ها توسط فایل‌های مبدأ تحت مستندسازی به ارث برده می‌شود نیز به کار می‌رود.

تنها زمانی می‌توانید از گزینهٔ -sourcepath استفاده کنید که نام بسته‌ها را به دستور javadoc ارسال می‌کنید. این گزینه فایل‌های مبدأ ارائه‌شده به دستور javadoc را مکان‌یابی نمی‌کند. برای مشخص کردن محل فایل‌های مبدأ، به آن دایرکتوری بروید یا همان‌طور که در بخش Document One or More Classes نشان داده شده است، مسیر را قبل از هر فایل درج کنید. اگر -sourcepath را نادیده بگیرید، دستور javadoc از مسیر کلاس برای یافتن فایل‌های مبدأ استفاده می‌کند (به -classpath مراجعه کنید). مقدار پیش‌فرض -sourcepath همان مقدار مسیر کلاس (class path) است. اگر -classpath درج نشود و نام بسته‌ها را به دستور javadoc ارسال کنید، دستور javadoc در دایرکتوری جاری و زیردایرکتوری‌های آن به جست‌وجوی فایل‌های مبدأ می‌پردازد.

مقدار sourcepathlist را روی دایرکتوری ریشهٔ درخت مبدأ برای بسته‌ای که مستند می‌کنید قرار دهید.

برای مثال، فرض کنید می‌خواهید بسته‌ای با نام com.mypackage را مستندسازی کنید که فایل‌های مبدأ آن در مسیر /home/user/src/com/mypackage/*.java قرار دارند. مقدار sourcepath را برابر با /home/user/src (دایرکتوری شامل com\mypackage) تعیین کرده و سپس نام بسته را به‌صورت زیر ارائه دهید:

javadoc -sourcepath /home/user/src/ com.mypackage

توجه داشته باشید که اگر مقدار sourcepath و نام بسته را به هم متصل کنید و نقطه را به یک اسلش (/) تغییر دهید، مسیر کامل منتهی به بسته را خواهید داشت:

/home/user/src/com/mypackage

برای اشاره به دو مسیر مبدأ:

javadoc -sourcepath /home/user1/src:/home/user2/src com.mypackage

-classpath classpathlist

مسیرهایی را مشخص می‌کند که دستور javadoc در آن‌ها به دنبال کلاس‌های ارجاع‌شده می‌گردد. این‌ها کلاس‌های مستندشده به‌علاوهٔ هر کلاسی هستند که توسط آن کلاس‌ها ارجاع داده شده‌اند. چندین مسیر را با دونقطه (:) جدا کنید. دستور javadoc تمام زیردایرکتوری‌های مسیرهای مشخص‌شده را جست‌وجو می‌کند. برای تعیین مقدار classpathlist، از دستورالعمل‌های موجود در مستندات مسیر کلاس (class path) پیروی کنید.

اگر -sourcepath را نادیده بگیرید، دستور javadoc از -classpath برای یافتن فایل‌های مبدأ و فایل‌های کلاس استفاده می‌کند (جهت سازگاری با نسخه‌های پیشین). اگر می‌خواهید فایل‌های مبدأ و کلاس را در مسیرهای جداگانه جست‌وجو کنید، از هر دو گزینهٔ -sourcepath و -classpath استفاده نمایید.

برای مثال، اگر می‌خواهید com.mypackage را مستندسازی کنید که فایل‌های مبدأ آن در دایرکتوری /home/user/src/com/mypackage قرار دارند، و این بسته به کتابخانه‌ای در /home/user/lib وابسته است، از دستور زیر استفاده کنید:

javadoc -sourcepath /home/user/lib -classpath /home/user/src com.mypackage

مشابه سایر ابزارها، اگر -classpath را مشخص نکنید، دستور javadoc در صورت تنظیم بودن متغیر محیطی CLASSPATH از آن استفاده می‌کند. اگر هیچ‌یک تنظیم نشده باشند، دستور javadoc به دنبال کلاس‌ها در دایرکتوری جاری می‌گردد.

برای شرح دقیق نحوهٔ استفادهٔ دستور javadoc از -classpath برای یافتن کلاس‌های کاربر در ارتباط با کلاس‌های افزونه (extension) و کلاس‌های خودراه‌انداز (bootstrap)، بخش How Classes Are Found را در http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html ببینید.

عنصری در مسیر کلاس که شامل نام پایهٔ * باشد، معادل تعیین فهرستی از تمام فایل‌های درون آن دایرکتوری با پسوند .jar یا .JAR در نظر گرفته می‌شود.

برای مثال، اگر دایرکتوری mydir حاوی a.jar و b.JAR باشد، عنصر مسیر کلاس foo/* به A.jar:b.JAR بسط داده می‌شود، جز اینکه ترتیب فایل‌های JAR نامشخص است. تمام فایل‌های JAR درون دایرکتوری مشخص‌شده، از جمله فایل‌های پنهان، در این فهرست قرار می‌گیرند. یک مدخل در مسیر کلاس که شامل * باشد، به فهرستی از تمام فایل‌های jar در دایرکتوری جاری بسط می‌یابد. متغیر محیطی CLASSPATH نیز به همین صورت بسط داده می‌شود. هرگونه بسط نویسه‌های عام (wildcard) در مسیر کلاس قبل از شروع به کار ماشین مجازی جاوا (JVM) رخ می‌دهد. هیچ برنامهٔ جاوایی هرگز نویسه‌های عام بسط‌نیافته را نمی‌بیند مگر از طریق پرس‌وجو از محیط، برای نمونه با فراخوانی System.getenv("CLASSPATH")..TP -subpackages package1:package2:...
مستندات را از فایل‌های منبع در بسته‌های مشخص‌شده و به‌صورت بازگشتی در زیربسته‌های آن‌ها تولید می‌کند. این گزینه زمانی که زیربسته‌های جدیدی را به کد منبع اضافه می‌کنید مفید است، زیرا آن‌ها به‌طور خودکار گنجانده می‌شوند. هر آرگومان بسته، هر زیربستهٔ سطح بالا (مانند java) یا یک بستهٔ کامل (مانند javax.swing) است که نیازی به داشتن فایل‌های منبع ندارد. آرگومان‌ها در تمام سیستم‌های عامل با دونقطه (:) از یکدیگر جدا می‌شوند. نویسه‌های عام (Wild cards) مجاز نیستند. از -sourcepath برای مشخص کردن محل یافتن بسته‌ها استفاده کنید. این گزینه فایل‌های منبعی را که در درخت منبع قرار دارند اما متعلق به بسته‌ها نیستند پردازش نمی‌کند. بخش Process Source Files را ببینید.

برای مثال، دستور زیر مستندات مربوط به بسته‌هایی با نام java و javax.swing و تمام زیربسته‌های آن‌ها را تولید می‌کند.

javadoc -d docs -sourcepath /home/user/src  -subpackages java:javax.swing 

-exclude packagename1:packagename2:...

به‌طور قطعی و بی‌قیدوشرط، بسته‌های مشخص‌شده و زیربسته‌های آن‌ها را از فهرستی که توسط -subpackages ساخته شده مستثنی می‌کند. این گزینه آن بسته‌ها را حتی در صورتی که توسط گزینهٔ -subpackages پیشین یا پسین دیگری گنجانده شده باشند، حذف می‌کند.

مثال زیر بسته‌های java.io، java.util و java.math (در کنار سایر بسته‌ها) را شامل می‌شود، اما بسته‌هایی را که ریشه در java.net و java.lang دارند مستثنی می‌سازد. توجه داشته باشید که این مثال java.lang.ref را که یک زیربسته از java.lang است، مستثنی می‌کند.

javadoc -sourcepath /home/user/src -subpackages java -exclude 

    java.net:java.lang

-bootclasspath classpathlist

مسیرهایی را مشخص می‌کند که کلاس‌های راه‌اندازی (boot classes) در آن قرار دارند. این‌ها معمولاً کلاس‌های پلتفرم جاوا هستند. مقدار bootclasspath بخشی از مسیر جستجویی است که دستور javadoc برای جستجوی فایل‌های منبع و فایل‌های کلاس استفاده می‌کند. برای اطلاعات بیشتر، بخش How Classes Are Found را در http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html ببینید.

دایرکتوری‌ها را در پارامترهای classpathlist برای Windows با نقطه-ویرگول (;) و برای Oracle Solaris با دونقطه (:) جدا کنید.

-extdirs dirist

دایرکتوری‌هایی را مشخص می‌کند که کلاس‌های افزونه (extension classes) در آن قرار دارند. این‌ها کلاس‌هایی هستند که از سازوکار افزونه جاوا (Java Extension) بهره می‌برند. گزینهٔ extdirs بخشی از مسیر جستجویی است که دستور javadoc برای یافتن فایل‌های منبع و کلاس به کار می‌برد. برای اطلاعات بیشتر گزینهٔ -classpath را ببینید. دایرکتوری‌ها را در dirlist با نقطه-ویرگول (;) برای Windows و با دونقطه (:) برای Oracle Solaris از هم جدا کنید.

-verbose

پیام‌های با جزئیات بیشتری را در هنگام اجرای دستور javadoc ارائه می‌دهد. بدون گزینهٔ verbose، پیام‌ها تنها برای بارگذاری فایل‌های منبع، تولید مستندات (یک پیام به ازای هر فایل منبع) و مرتب‌سازی نمایش می‌یابند. گزینهٔ verbose موجب چاپ پیام‌های اضافی می‌شود که مدت زمان لازم (به میلی‌ثانیه) را برای تجزیهٔ هر فایل منبع جاوا مشخص می‌کنند.

-quiet

پیام‌ها را قطع می‌کند تا فقط هشدارها و خطاها نمایش داده شوند و بررسی آن‌ها آسان‌تر شود. این گزینه همچنین رشتهٔ version را پنهان می‌سازد.

-breakiterator

از مرز جملهٔ بین‌المللی‌شدهٔ java.text.BreakIterator برای تعیین انتهای جملهٔ اول در توضیحات اصلی یک بسته، کلاس یا عضو برای زبان انگلیسی استفاده می‌کند. سایر محلی‌سازی‌ها از پیش به جای الگوریتم خاص زبان انگلیسی، از کلاس BreakIterator استفاده می‌کنند. اولین جمله در خلاصهٔ بسته، کلاس یا عضو و در نمایهٔ الفبایی کپی می‌شود. از نسخهٔ JDK 1.2 به بعد، کلاس BreakIterator برای تعیین انتهای جمله برای تمام زبان‌ها به جز انگلیسی استفاده می‌شود. بنابراین، گزینهٔ -breakiterator از نسخهٔ 1.2 به بعد برای هیچ زبانی به جز انگلیسی اثری ندارد. زبان انگلیسی الگوریتم پیش‌فرض خاص خود را دارد:

در Java SE 1.5 پیام‌های هشدار گزینهٔ -breakiterator حذف شده‌اند و الگوریتم پیش‌فرض شکست جمله بدون تغییر باقی مانده است. اگر کد منبع خود را برای حذف هشدارهای گزینهٔ -breakiterator در Java SE 1.4.x دستکاری نکرده‌اید، نیازی به انجام کاری ندارید. این هشدارها از نسخهٔ Java SE 1.5.0 برطرف شده‌اند.

-locale language_country_variant

محلی‌سازی (locale) مورد استفاده توسط دستور javadoc را هنگام تولید مستندات مشخص می‌کند. این آرگومان نام locale است، همان‌گونه که در مستندات java.util.Locale شرح داده شده، مانند en_US (انگلیسی، ایالات متحده) یا en_US_WIN (گونهٔ Windows).

نکته: گزینهٔ -locale باید جلوتر (در سمت چپ) تمام گزینه‌های ارائه‌شده توسط doclet استاندارد یا هر doclet دیگری قرار گیرد. در غیر این صورت، نوارهای ناوبری به زبان انگلیسی نمایش داده می‌شوند. این تنها گزینهٔ خط فرمان است که به ترتیب قرارگیری وابسته است. بخش Standard Doclet Options را ببینید.

تعیین محلی‌سازی موجب می‌شود دستور javadoc فایل‌های منبع (resource files) آن locale را برای پیام‌هایی چون رشته‌های نوار ناوبری، سرتیترهای فهرست‌ها و جدول‌ها، محتوای فایل راهنما، کامنت‌های فایل stylesheet.css و غیره برگزیند. این گزینه همچنین ترتیب مرتب‌سازی برای فهرست‌های الفبایی و جداکنندهٔ جملات را برای تعیین انتهای اولین جمله مشخص می‌سازد. گزینهٔ -locale تعیین‌کنندهٔ locale متن کامنت‌های مستنداتی موجود در فایل‌های منبع کلاس‌های مستندشده نیست.

-encoding

نام کدگذاری (encoding) فایل‌های منبع را مشخص می‌کند، مانند EUCJIS/SJIS. در صورت عدم تعیین این گزینه، مبدل پیش‌فرض پلتفرم استفاده می‌شود. همچنین گزینه‌های -docencoding name و -charset name را ببینید.

-Jflag

پرچم flag را مستقیماً به محیط زمان اجرای جاوا (JRE) که دستور javadoc را اجرا می‌کند ارسال می‌نماید. برای نمونه، اگر بخواهید اطمینان حاصل کنید که سیستم ۳۲ مگابایت حافظه برای پردازش مستندات تولیدشده اختصاص می‌دهد، گزینهٔ -Xmx را بدین صورت فراخوانی می‌کنید: javadoc -J-Xmx32m -J-Xms32m com.mypackage. توجه داشته باشید که -Xms اختیاری است زیرا صرفاً اندازهٔ حافظهٔ اولیه را تعیین می‌کند، که این ویژگی زمانی که حداقل حافظهٔ مورد نیاز را می‌دانید کاربرد دارد.

بین J و flag نباید هیچ فاصله‌ای وجود داشته باشد.

برای اطلاع از نسخهٔ دستور javadoc که از آن استفاده می‌کنید، گزینهٔ -version را به کار ببرید. شماره نسخهٔ doclet استاندارد در خروجی آن نمایش می‌یابد. بخش Running the Javadoc Command را ببینید.

javadoc -J-version

java version "1.7.0_09"

Java(TM) SE Runtime Environment (build 1.7.0_09-b05)

Java HotSpot(TM) 64-Bit Server VM (build 23.5-b02, mixed mode)

-javafx

مستندات HTML را با بهره‌گیری از افزونه‌های JavaFX روی doclet استاندارد تولید می‌کند. مستندات تولیدشده علاوه بر سایر بخش‌های خلاصهٔ ایجادشده توسط doclet استاندارد جاوا، شامل یک بخش خلاصه ویژگی (Property Summary) نیز خواهد بود. ویژگی‌های فهرست‌شده به بخش‌های متدهای getter و setter مربوط به هر ویژگی پیوند دارند.

اگر کامنت‌های مستنداتی به‌طور صریح برای متدهای getter و setter نوشته نشده باشد، کامنت‌های مستندات متد ویژگی به‌طور خودکار به مستندات تولیدشده برای این متدها رونوشت می‌شود. این گزینه همچنین یک برچسب جدید به نام @defaultValue اضافه می‌کند که امکان مستندسازی مقدار پیش‌فرض یک ویژگی را فراهم می‌سازد.

مثال:

javadoc -javafx MyClass.java -d testdir

گزینه‌های استاندارد DOCLET (STANDARD DOCLET OPTIONS)

-d directory

دایرکتوری مقصدی را مشخص می‌کند که دستور javadoc فایل‌های HTML تولیدشده را در آن ذخیره می‌نماید. در صورت حذف گزینهٔ -d، فایل‌ها در دایرکتوری جاری ذخیره می‌شوند. مقدار directory می‌تواند مطلق یا نسبت به دایرکتوری کاری فعلی باشد. از نسخهٔ Java SE 1.4، دایرکتوری مقصد در زمان اجرای دستور javadoc به‌طور خودکار ساخته می‌شود.

برای مثال، دستور زیر مستندات بستهٔ com.mypackage را تولید کرده و نتایج را در دایرکتوری /user/doc/ ذخیره می‌کند: javadoc -d /user/doc/ com.mypackage.

-use

یک برگهٔ Use (کاربرد) برای هر کلاس و بستهٔ مستندشده ایجاد می‌کند. این صفحه مشخص می‌کند که چه بسته‌ها، کلاس‌ها، متدها، سازنده‌ها و فیلدهایی از هر API کلاس یا بستهٔ مشخص‌شده استفاده می‌کنند. به عنوان نمونه برای کلاس C، مواردی که از کلاس C استفاده می‌کنند شامل زیرکلاس‌های C، فیلدهای تعریف‌شده از نوع C، متدهایی که مقدار بازگشتی آن‌ها C است و متدها و سازنده‌هایی با پارامترهایی از نوع C خواهد بود. برای مثال، می‌توانید به برگهٔ Use برای نوع String نگاه کنید. از آنجا که متد getName در کلاس java.awt.Font نوع String برمی‌گرداند، این متد از String استفاده می‌کند و در نتیجه در برگهٔ Use برای String نمایش می‌یابد. این ویژگی تنها استفاده‌ها از API را مستند می‌کند، نه پیاده‌سازی را. هنگامی که یک متد در پیاده‌سازی خود از String استفاده می‌کند، اما رشته‌ای به عنوان آرگومان دریافت نکرده یا آن را برنمی‌گرداند، این مورد به عنوان استفاده از String لحاظ نمی‌شود. برای دسترسی به صفحهٔ Use تولیدشده، به صفحهٔ کلاس یا بسته رفته و روی پیوند Use در نوار ناوبری کلیک کنید.

-version

متن @version را در اسناد تولیدشده قرار می‌دهد. این متن به‌طور پیش‌فرض حذف می‌شود. برای یافتن نسخهٔ مورد استفادهٔ دستور javadoc، از گزینهٔ -J-version استفاده کنید.

-author

متن @author را در اسناد تولیدشده قرار می‌دهد.

-splitindex

فایل نمایه را به چندین فایل، بر اساس حروف الفبا، یک فایل برای هر حرف، به‌علاوهٔ یک فایل برای هر مدخل نمایه‌ای که با نمادهای غیرحرفی آغاز می‌شود تقسیم می‌کند.

-windowtitle title

عنوانی را برای قرار گرفتن در برچسب HTML <title> مشخص می‌کند. متنی که در برچسب title تعیین می‌شود در عنوان پنجره و در نشانک‌های مرورگر که کاربران برای این صفحه می‌سازند نمایش داده می‌شود. این عنوان نباید حاوی برچسب‌های HTML باشد زیرا مرورگر آن‌ها را به‌درستی تفسیر نمی‌کند. برای هر علامت نقل‌قول درونی در برچسب title از نویسه‌های گریز (escape) استفاده کنید. اگر گزینهٔ -windowtitle حذف شود، دستور javadoc از مقدار گزینهٔ -doctitle برای -windowtitle استفاده می‌کند. برای مثال، javadoc -windowtitle "Java SE Platform" com.mypackage.

-doctitle title

عنوانی را برای قرار گرفتن در نزدیکی بالای فایل خلاصهٔ نمای کلی مشخص می‌کند. متنی که در برچسب title مشخص می‌شود، به عنوان یک سرتیتر سطح‌یک و وسط‌چین مستقیماً در زیر نوار ناوبری بالایی قرار می‌گیرد. برچسب title می‌تواند شامل برچسب‌های HTML و فاصله باشد، اما در این صورت، باید عنوان را در علامت نقل‌قول محصور کنید. علامت‌های نقل‌قول درونی در برچسب title باید گریز داده شوند. برای مثال: javadoc -header "<b>Java Platform </b><br>v1.4" com.mypackage.

-title title

دیگر وجود ندارد. این گزینه فقط در نسخه‌های بتای Javadoc 1.2 وجود داشت و به -doctitle تغییر نام پیدا کرد. این تغییر نام انجام شد تا مشخص شود این گزینه عنوان سند را تعیین می‌کند، نه عنوان پنجره را.

-header header

متن سربرگ را برای قرار گرفتن در بالای هر فایل خروجی مشخص می‌کند. سربرگ در سمت راست نوار ناوبری بالایی قرار می‌گیرد. مقدار header می‌تواند حاوی برچسب‌های HTML و فاصله باشد، اما در این حالت باید در علامت نقل‌قول قرار گیرد. برای علامت‌های نقل‌قول درونی در یک سربرگ از نویسه‌های گریز استفاده کنید. برای مثال: javadoc -header "<b>Java Platform </b><br>v1.4" com.mypackage.

-footer footer

متن پاورقی را برای قرار گرفتن در پایین هر فایل خروجی مشخص می‌کند. مقدار footer در سمت راست نوار ناوبری پایینی قرار می‌گیرد. مقدار footer می‌تواند شامل برچسب‌های HTML و فاصله باشد، اما در این صورت باید درون علامت‌های نقل‌قول قرار گیرد. برای هر نقل‌قول درونی در پاورقی از نویسه‌های گریز استفاده کنید.

-top

متنی را برای قرار گرفتن در بالای هر فایل خروجی مشخص می‌کند.

-bottom text

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

-link extdocURL

پیوندهایی به مستندات موجودِ تولیدشده توسط Javadoc برای کلاس‌های مرجع خارجی ایجاد می‌کند. آرگومان extdocURL نشانی URL مطلق یا نسبی دایرکتوری‌ای است که مستندات خارجی ساخته‌شده توسط Javadoc را در خود دارد. می‌توانید چندین گزینهٔ -link را در یک اجرای دستور javadoc برای پیوند دادن به چندین سند مشخص کنید.

فایل package-list باید در این دایرکتوری یافت شود (در غیر این صورت، از گزینهٔ -linkoffline استفاده کنید). دستور javadoc نام بسته‌ها را از فایل package-list می‌خواند و به آن بسته‌ها در آن نشانی URL پیوند ایجاد می‌کند. هنگامی که دستور javadoc اجرا می‌شود، مقدار extdocURL در پیوندهای <A HREF> ساخته‌شده رونوشت می‌شود. بنابراین، extdocURL باید نشانی دایرکتوری باشد، نه یک فایل. شما می‌توانید از یک پیوند مطلق برای extdocURL استفاده کنید تا اسناد شما امکان پیوند به سندی روی هر وب‌سایتی را داشته باشند، یا می‌توانید از پیوند نسبی برای پیوند تنها به یک موقعیت مکانی نسبی بهره بگیرید. در صورت استفاده از پیوند نسبی، مقداری که ارائه می‌دهید باید مسیر نسبی از دایرکتوری مقصد (مشخص‌شده با گزینهٔ -d) به دایرکتوری حاوی بسته‌های مورد پیوند باشد. هنگام تعیین پیوند مطلق، معمولاً از پیوند HTTP استفاده می‌شود. با این حال، اگر می‌خواهید به سیستم فایلی که فاقد وب‌سرور است پیوند دهید، می‌توانید از پیوند file استفاده کنید. پیوند file را تنها زمانی به کار ببرید که همهٔ افرادی که به مستندات تولیدشده دسترسی دارند، در سیستم فایل یکسانی مشترک باشند. در تمامی موارد و در تمامی سیستم‌های عامل، از ممیز (اسلش) به عنوان جداکننده استفاده کنید، خواه URL مطلق باشد یا نسبی، و همان‌طور که در یادداشت URL: Uniform Resource Locators در http://www.ietf.org/rfc/rfc1738.txt مشخص شده است، از http: یا file: استفاده کنید.

-link  http://<host>/<directory>/<directory>/.../<name>

-link file://<host>/<directory>/<directory>/.../<name>

-link <directory>/<directory>/.../<name>

تفاوت‌های بین گزینه‌های -linkoffline و -link

از گزینهٔ -link در موارد زیر استفاده کنید:

•

هنگامی که از مسیر نسبی به سند API خارجی استفاده می‌کنید.

•

هنگامی که از نشانی URL مطلق به سند API خارجی استفاده می‌کنید در صورتی که پوستهٔ (shell) شما اجازهٔ باز کردن اتصال به آن URL را برای خواندن فراهم سازد..PP هنگامی که از یک URL مطلق برای سند API خارجی استفاده می‌کنید، اگر شل شما به برنامه‌ای اجازه باز کردن اتصال به آن URL برای خواندن را نمی‌دهد، از گزینه -linkoffline استفاده کنید. این حالت می‌تواند زمانی رخ دهد که پشت یک فایروال قرار دارید و سندی که می‌خواهید به آن پیوند دهید در سمت دیگر آن است.

مثال ۱: پیوند مطلق به اسناد خارجی

اگر می‌خواهید به بسته‌های java.lang، java.io و سایر بسته‌های پلتفرم Java که در http://docs.oracle.com/javase/8/docs/api/index.html نشان داده شده‌اند پیوند برقرار کنید، از دستور زیر استفاده کنید:

javadoc -link http://docs.oracle.com/javase/8/docs/api com.mypackage

این دستور مستندات را برای بسته com.mypackage همراه با پیوندهایی به بسته‌های Java SE تولید می‌کند. مستندات تولیدشده به عنوان مثال در درخت کلاس‌ها (trees)، شامل پیوندهایی به کلاس Object خواهد بود. سایر گزینه‌ها مانند گزینه‌های -sourcepath و -d نشان داده نشده‌اند.

مثال ۲: پیوند نسبی به اسناد خارجی

در این مثال، دو بسته با مستنداتی وجود دارند که در اجراهای متفاوتی از دستور javadoc تولید می‌شوند و این مستندات با یک مسیر نسبی از یکدیگر جدا شده‌اند. این بسته‌ها عبارتند از com.apipackage (یک API) و com.spipackage (یک رابط ارائه‌دهنده خدمات یا SPI). شما می‌خواهید مستندات در docs/api/com/apipackage و docs/spi/com/spipackage قرار گیرند. با فرض اینکه مستندات بسته API از قبل تولید شده است و docs دایرکتوری جاری است، با اجرای دستور زیر بسته SPI را با پیوندهایی به مستندات API مستندسازی می‌کنید: javadoc -d ./spi -link ../api com.spipackage.

توجه داشته باشید که گزینه -link نسبت به دایرکتوری مقصد (docs/spi) نسبی است.

نکات

گزینه -link به شما امکان می‌دهد به کلاس‌هایی پیوند دهید که در کد شما به آن‌ها ارجاع داده شده، اما در اجرای فعلی دستور javadoc مستندسازی نشده‌اند. برای اینکه این پیوندها به صفحات معتبری هدایت شوند، باید بدانید آن صفحات HTML در کجا قرار دارند و آن مکان را با extdocURL مشخص کنید. این کار به مستندات شخص ثالث اجازه می‌دهد به مستندات java.* در http://docs.oracle.com پیوند دهند. هنگامی که می‌خواهید دستور javadoc فقط به APIهای درون مستنداتی که در اجرای فعلی تولید می‌شوند پیوند ایجاد کند، گزینه -link را حذف کنید. بدون گزینه -link، دستور javadoc پیوندی به مستندات ارجاعات خارجی ایجاد نمی‌کند، زیرا نمی‌داند آیا چنین مستنداتی وجود دارند یا در کجا قرار دارند. گزینه -link می‌تواند در چندین بخش از مستندات تولیدشده پیوند ایجاد کند؛ بخش Process Source Files را ببینید. کاربرد دیگر برای پیوندهای متقابل (cross-links) بین مجموعه‌هایی از بسته‌ها است: دستور javadoc را روی یک مجموعه از بسته‌ها اجرا کنید، سپس دستور javadoc را دوباره روی مجموعه دیگری از بسته‌ها اجرا نمایید و بدین ترتیب پیوندهای دوطرفه بین هر دو مجموعه ایجاد کنید.

نحوه ارجاع به یک کلاس

برای اینکه پیوند به یک کلاس ارجاع داده‌شده خارجی ظاهر شود (و نه صرفاً برچسب متنی آن)، کلاس باید به شیوه زیر ارجاع داده شود. ارجاع به آن در بدنه یک متد کافی نیست. باید در یک عبارت import یا در یک اعلان (declaration) به آن ارجاع داده شود. در اینجا مثال‌هایی از نحوه ارجاع به کلاس java.io.File آمده است:

در هر نوع عبارت import: با استفاده از نویسه عمومی (wildcard import)، وارد کردن صریح با نام، یا وارد کردن خودکار برای java.lang.*.

در Java SE نسخه 1.3.n و 1.2.n، تنها وارد کردن صریح با نام کار می‌کند. عبارت import با نویسه عمومی کار نمی‌کند، و همچنین import java.lang.* خودکار نیز عمل نمی‌کند.

در یک اعلان: void mymethod(File f) {}

این ارجاع می‌تواند در نوع بازگشتی یا نوع پارامتر یک متد، سازنده (constructor)، فیلد، کلاس یا رابط (interface)، یا در عبارات implements، extends یا throws باشد.

یک نتیجه مهم این است که هنگام استفاده از گزینه -link، ممکن است پیوندهای زیادی به دلیل این محدودیت ناخواسته ظاهر نشوند. متن بدون اینکه یک پیوند باشد نمایش داده خواهد شد. می‌توانید این موارد را از روی هشدارهایی که صادر می‌کنند شناسایی کنید. ساده‌ترین راه برای ارجاع مناسب به یک کلاس و افزودن پیوند، وارد کردن (import) آن کلاس است.

فهرست بسته‌ها (Package List)

گزینه -link مستلزم آن است که فایلی با نام package-list، که توسط دستور javadoc تولید می‌شود، در URL تعیین‌شده با گزینه -link وجود داشته باشد. فایل package-list یک فایل متنی ساده است که نام بسته‌های مستندسازی‌شده در آن مکان را فهرست می‌کند. در مثال قبلی، دستور javadoc به دنبال فایلی به نام package-list در URL مشخص‌شده می‌گردد، نام بسته‌ها را می‌خواند و به آن بسته‌ها در آن URL پیوند می‌دهد.

برای مثال، فهرست بسته‌ها برای Java SE API در http://docs.oracle.com/javase/8/docs/api/package-list قرار دارد.

فهرست بسته‌ها به صورت زیر آغاز می‌شود:

java.applet

java.awt

java.awt.color

java.awt.datatransfer

java.awt.dnd

java.awt.event

java.awt.font

and so on ....

هنگامی که javadoc بدون گزینه -link اجرا می‌شود و به نامی برمی‌خورد که متعلق به یک کلاس ارجاع داده‌شده خارجی است، نام را بدون هیچ پیوندی چاپ می‌کند. با این حال، هنگامی که گزینه -link استفاده می‌شود، دستور javadoc فایل package-list را در مکان مشخص‌شده توسط extdocURL برای یافتن نام آن بسته جستجو می‌کند. هنگامی که نام بسته را پیدا کرد، extdocURL را به عنوان پیشوند به نام اضافه می‌کند.

برای اینکه هیچ پیوند شکسته‌ای وجود نداشته باشد، تمام مستندات مربوط به ارجاعات خارجی باید در URLهای مشخص‌شده موجود باشند. دستور javadoc وجود این صفحات را بررسی نمی‌کند، بلکه تنها وجود package-list را بررسی می‌نماید.

پیوندهای چندگانه

می‌توانید چندین گزینه -link را برای پیوند به هر تعداد سند تولیدشده خارجی ارائه دهید. در Javadoc 1.2 یک باگ شناخته‌شده وجود دارد که مانع از ارائه بیش از یک گزینه -link می‌شود. این مشکل در Javadoc 1.2.2 برطرف شد. برای هر سند خارجی که می‌خواهید به آن پیوند دهید یک گزینه پیوند جداگانه مشخص کنید: javadoc -link extdocURL1 -link extdocURL2 ... -link extdocURLn com.mypackage که در آن extdocURL1، extdocURL2، ... extdocURLn به ترتیب به ریشه اسناد خارجی اشاره دارند که هر کدام حاوی فایلی به نام package-list هستند.

پیوندهای متقابل (Cross Links)

توجه داشته باشید هنگام پیوند متقابل بین دو یا چند سند که قبلاً تولید شده‌اند، ممکن است خودراه‌اندازی (bootstrapping) لازم باشد. اگر هنگام اجرای دستور javadoc بر روی سند اول، package-list برای هیچ‌یک از اسناد وجود نداشته باشد، در نتیجه package-list هنوز برای سند دوم نیز وجود ندارد. بنابراین، برای ایجاد پیوندهای خارجی، باید پس از تولید سند دوم، سند اول را مجدداً تولید کنید.

در این حالت، هدف از تولید اولیه یک سند، ایجاد فایل package-list آن است (یا در صورت اطمینان از نام بسته‌ها می‌توانید آن را دستی بسازید). سپس، سند دوم را به همراه پیوندهای خارجی آن تولید کنید. دستور javadoc در صورتی که فایل خارجی package-list مورد نیاز وجود نداشته باشد، یک هشدار چاپ می‌کند.

-linkoffline extdocURL packagelistLoc

این گزینه گونه‌ای از گزینه -link است. هر دوی آن‌ها پیوندهایی به مستندات تولیدشده توسط Javadoc برای کلاس‌های ارجاع داده‌شده خارجی ایجاد می‌کنند. هنگامی که دستور javadoc نمی‌تواند از طریق اتصال وب به سندی دسترسی پیدا کند، برای پیوند به آن سند در وب از گزینه -linkoffline استفاده کنید. زمانی از گزینه -linkoffline استفاده کنید که فایل package-list سند خارجی در مکان extdocURL قابل دسترسی نبوده یا وجود ندارد، اما در مکان متفاوتی که با packageListLoc مشخص می‌شود (معمولاً محلی) وجود دارد. اگر extdocURL فقط در وب جهانی قابل دسترسی است، گزینه -linkoffline این محدودیت را که دستور javadoc برای تولید مستندات الزاماً باید اتصال وب داشته باشد برطرف می‌کند. کاربرد دیگر به عنوان یک راهکار برای به‌روزرسانی اسناد است: پس از اجرای دستور javadoc روی یک مجموعه کامل از بسته‌ها، می‌توانید دستور javadoc را دوباره روی مجموعه کوچک‌تری از بسته‌های تغییریافته اجرا کنید، تا فایل‌های به‌روزرسانی‌شده بتوانند مجدداً درون مجموعه اصلی جای‌گذاری شوند. در ادامه مثال‌هایی ارائه شده است. گزینه -linkoffline دو آرگومان می‌گیرد: اولی رشته‌ای است که باید در پیوندهای <a href> تعبیه شود، و دومی به گزینه -linkoffline اعلام می‌کند فایل package-list را در کجا پیدا کند:

پیوندهای مطلق به اسناد خارجی

ممکن است در شرایطی باشید که بخواهید به بسته‌های java.lang، java.io و سایر بسته‌های Java SE در http://docs.oracle.com/javase/8/docs/api/index.html پیوند دهید.

با این حال، شل شما به وب دسترسی ندارد. در این حالت، مراحل زیر را انجام دهید:

1.

فایل package-list را در یک مرورگر در آدرس http://docs.oracle.com/javase/8/docs/api/package-list باز کنید.

2.

فایل را در یک دایرکتوری محلی ذخیره کرده و با آرگومان دوم، packagelistLoc، به این نسخه محلی اشاره کنید. در این مثال، فایل فهرست بسته‌ها در دایرکتوری جاری (.) ذخیره شده است.

دستور زیر مستندات را برای بسته com.mypackage همراه با پیوندهایی به بسته‌های Java SE تولید می‌کند. مستندات تولیدشده به عنوان مثال در درخت کلاس‌ها (trees)، شامل پیوندهایی به کلاس Object خواهد بود. سایر گزینه‌های ضروری مانند -sourcepath نشان داده نشده‌اند.

javadoc -linkoffline http://docs.oracle.com/javase/8/docs/api .  com.mypackage 

پیوندهای نسبی به اسناد خارجی

استفاده از -linkoffline با مسیرهای نسبی چندان رایج نیست، به این دلیل ساده که گزینه -link معمولاً کافی است. هنگامی که از گزینه -linkoffline استفاده می‌کنید، فایل package-list معمولاً محلی است، و هنگامی که از پیوندهای نسبی استفاده می‌کنید، فایلی که به آن پیوند می‌دهید نیز محلی است؛ بنابراین معمولاً نیازی به ارائه مسیر متفاوت برای دو آرگومان گزینه -linkoffline وجود ندارد. هنگامی که هر دو آرگومان یکسان باشند، می‌توانید از گزینه -link استفاده کنید.

ایجاد دستی فایل package-list

اگر فایل package-list هنوز وجود ندارد، اما می‌دانید سند شما به چه نام بسته‌هایی پیوند خواهد خورد، می‌توانید به صورت دستی نسخه خود را از این فایل ایجاد کنید و مسیر آن را با packagelistLoc مشخص نمایید. یک مثال می‌تواند همان مورد قبلی باشد که در آن هنگام تولید اولیه com.apipackage، فهرست بسته‌ها برای com.spipackage وجود نداشت. این روش زمانی مفید است که نیاز به تولید مستنداتی دارید که به مستندات خارجی جدیدی پیوند دارند که نام بسته‌های آن‌ها را می‌دانید، اما هنوز منتشر نشده‌اند. همچنین این روشی برای ایجاد فایل‌های package-list برای بسته‌های تولیدشده با Javadoc 1.0 یا 1.1 است که در آن‌ها فایل package-list تولید نمی‌شد. به همین ترتیب، دو شرکت می‌توانند فایل‌های package-list منتشرنشده خود را به اشتراک بگذارند تا بتوانند مستندات با پیوند متقابل خود را به طور همزمان عرضه کنند.

پیوند به چندین سند

می‌توانید به ازای هر سند تولیدشده‌ای که می‌خواهید به آن ارجاع دهید، یک‌بار گزینه -linkoffline را مشخص کنید:

javadoc -linkoffline extdocURL1 packagelistLoc1 -linkoffline extdocURL2

packagelistLoc2 ...

به‌روزرسانی اسناد

همچنین می‌توانید زمانی که پروژه‌تان ده‌ها یا صدها بسته دارد، از گزینه -linkoffline استفاده کنید. اگر پیش‌تر دستور javadoc را روی کل درخت کد مبدأ اجرا کرده‌اید، می‌توانید به سرعت تغییرات کوچکی در کامنت‌های مستندسازی (documentation comments) اعمال کرده و دستور javadoc را روی بخشی از درخت کد مبدأ دوباره اجرا کنید. توجه داشته باشید که اجرای دوم تنها زمانی به درستی کار می‌کند که تغییرات شما صرفاً در کامنت‌های مستندسازی باشد و نه در اعلان‌ها. اگر هرگونه اعلانی را به کد مبدأ اضافه یا حذف کنید یا تغییر دهید، ممکن است پیوندهای شکسته در نمایه (index)، درخت بسته (package tree)، فهرست‌های اعضای موروثی، صفحه Use و جاهای دیگر ظاهر شوند.

ابتدا یک دایرکتوری مقصد جدید، مانند update، برای این اجرای کوچک جدید ایجاد کنید. در این مثال، نام دایرکتوری مقصد اصلی html است. در ساده‌ترین مثال، به دایرکتوری والد html بروید. آرگومان اول گزینه -linkoffline را روی دایرکتوری جاری (.) تنظیم کرده و آرگومان دوم را روی مسیر نسبی به html، جایی که می‌تواند package-list را بیابد، تنظیم نمایید و تنها نام بسته‌هایی را که می‌خواهید به‌روزرسانی شوند وارد کنید:

javadoc -d update -linkoffline . html com.mypackage

پس از اتمام دستور javadoc، این صفحات کلاس تولیدشده در update/com/package را (نه نمای کلی overview یا نمایه index) روی فایل‌های اصلی در html/com/package کپی کنید.

-linksource

یک نسخه HTML از هر فایل مبدأ (همراه با شماره خطوط) ایجاد کرده و پیوندهایی از مستندات HTML استاندارد به آن‌ها اضافه می‌کند. پیوندها برای کلاس‌ها، رابط‌ها، سازنده‌ها، متدها و فیلدهایی که اعلان آن‌ها در یک فایل مبدأ است ایجاد می‌شوند. در غیر این صورت، پیوندی ایجاد نمی‌شود؛ مانند سازنده‌های پیش‌فرض و کلاس‌های تولیدشده.

این گزینه تمام جزئیات پیاده‌سازی خصوصی را در فایل‌های مبدأ مشخص‌شده آشکار می‌کند، از جمله کلاس‌های خصوصی، فیلدهای خصوصی و بدنه متدهای خصوصی، صرف‌نظر از گزینه‌های -public، -package، -protected و -private. مگر اینکه از گزینه -private نیز استفاده کنید، همه کلاس‌ها یا رابط‌های خصوصی از طریق پیوندها قابل دسترسی نخواهند بود.

هر پیوند روی نام شناسه در اعلان آن ظاهر می‌شود. به عنوان مثال، پیوند به کد مبدأ کلاس Button روی کلمه Button خواهد بود:

public class Button extends Component implements Accessible

پیوند به کد مبدأ متد getLabel در کلاس Button روی کلمه getLabel قرار دارد:

public String getLabel()

-group groupheading packagepattern:packagepattern

بسته‌ها را در صفحه مرور کلی (overview) بر اساس گروه‌هایی که مشخص می‌کنید دسته‌بندی می‌کند، یک گروه در هر جدول. شما هر گروه را با یک گزینه -group مجزا مشخص می‌کنید. گروه‌ها به ترتیبی که در خط فرمان مشخص شده‌اند در صفحه ظاهر می‌شوند. بسته‌ها در داخل یک گروه به ترتیب الفبا مرتب می‌شوند. برای یک گزینه -group معین، بسته‌های منطبق با فهرست عبارات packagepattern در جدولی با عنوان groupheading نمایش داده می‌شوند.

هنگامی که گزینهٔ -group را مشخص نکنید، همهٔ بسته‌ها در یک گروه با عنوان Packages و زیرعنوان‌های مناسب قرار می‌گیرند. اگر زیرعنوان‌ها شامل همهٔ بسته‌های مستندسازی‌شده نباشند (همهٔ گروه‌ها)، بسته‌های باقی‌مانده در گروهی جداگانه با زیرعنوان Other Packages ظاهر می‌شوند.

به عنوان مثال، دستور javadoc زیر بسته‌های مستندسازی‌شده را به سه دستهٔ Core، Extension و Other Packages تفکیک می‌کند. نقطهٔ انتهایی (.) در java.lang* ظاهر نمی‌شود. گنجاندن نقطه، مانند java.lang.*، بستهٔ java.lang را حذف می‌کند.

javadoc -group "Core Packages" "java.lang*:java.util"

        -group "Extension Packages" "javax.*"

        java.lang java.lang.reflect java.util javax.servlet java.new

Core Packages

java.lang

java.lang.reflect

java.util

Extension Packages

javax.servlet

Other Packages

java.new

-nodeprecated

از تولید هرگونه API منسوخ‌شده (deprecated) در مستندات جلوگیری می‌کند. این گزینه کاری را انجام می‌دهد که گزینهٔ -nodeprecatedlist انجام می‌دهد، بعلاوه در بقیهٔ بخش‌های مستندات نیز هیچ API منسوخ‌شده‌ای تولید نمی‌کند. این ویژگی هنگام نوشتن کد، زمانی که نمی‌خواهید تمرکزتان توسط کدهای منسوخ‌شده برهم بخورد، مفید است.

-nodeprecatedlist

از تولید فایلی که شامل فهرست APIهای منسوخ‌شده است (deprecated-list.html) و پیوند موجود در نوار ناوبری به آن صفحه جلوگیری می‌کند. دستور javadoc همچنان به تولید APIهای منسوخ‌شده در سرتاسر سایر بخش‌های سند ادامه می‌دهد. این ویژگی زمانی مفید است که کد مبدأ شما فاقد هرگونه API منسوخ‌شده باشد و بخواهید نوار ناوبری خلوت‌تری داشته باشید.

-nosince

بخش‌های Since مربوط به برچسب‌های @since را از اسناد تولیدشده حذف می‌کند.

-notree

صفحات سلسله‌مراتب کلاس/رابط را از اسناد تولیدشده حذف می‌کند. این‌ها صفحاتی هستند که با استفاده از دکمهٔ Tree در نوار ناوبری به آن‌ها دسترسی پیدا می‌کنید. این سلسله‌مراتب به‌طور پیش‌فرض تولید می‌شود.

-noindex

نمایه (index) را از اسناد تولیدشده حذف می‌کند. نمایه به‌طور پیش‌فرض تولید می‌شود.

-nohelp

پیوند HELP را از نوارهای ناوبری در بالا و پایین هر صفحه از خروجی حذف می‌کند.

-nonavbar

از تولید نوار ناوبری، سربرگ و پابرگ که معمولاً در بالا و پایین صفحات تولیدشده وجود دارند، جلوگیری می‌کند. گزینهٔ -nonavbar هیچ تأثیری بر گزینهٔ -bottom ندارد. گزینهٔ -nonavbar زمانی مفید است که فقط به محتوا علاقه دارید و نیازی به ناوبری ندارید، مانند زمانی که فایل‌ها را صرفاً برای چاپ به PostScript یا PDF تبدیل می‌کنید.

-helpfile path\filename

مسیر یک فایل راهنمای جایگزین path\filename را مشخص می‌کند که پیوند HELP در نوارهای ناوبری بالا و پایین به آن ارجاع می‌دهد. بدون این گزینه، دستور javadoc یک فایل راهنمای help-doc.html ایجاد می‌کند که مسیر آن در خودِ دستور javadoc کدگذاری ثابت شده است. این گزینه به شما امکان می‌دهد رفتار پیش‌فرض را بازنویسی کنید. نام فایل می‌تواند هر نامی باشد و محدود به help-doc.html نیست. دستور javadoc پیوندهای نوار ناوبری را بر همان اساس تنظیم می‌کند، برای مثال:

javadoc -helpfile /home/user/myhelp.html java.awt.

-stylesheet path/filename

مسیر یک فایل شیوه‌نامهٔ (stylesheet) جایگزین HTML را مشخص می‌کند. بدون این گزینه، دستور javadoc به‌طور خودکار یک فایل شیوه‌نامه به نام stylesheet.css ایجاد می‌کند که درون دستور javadoc به صورت کدگذاری ثابت تعبیه شده است. این گزینه امکان بازنویسی مقدار پیش‌فرض را فراهم می‌کند. نام فایل می‌تواند هر نامی باشد و محدود به stylesheet.css نیست، برای مثال:

javadoc -stylesheet file /home/user/mystylesheet.css com.mypackage

-serialwarn

هشدارهای زمان ترجمه (کامپایل) را برای برچسب‌های گم‌شدهٔ @serial تولید می‌کند. به‌طور پیش‌فرض، Javadoc 1.2.2 و نسخه‌های پس از آن هیچ هشدار سریالی‌سازی تولید نمی‌کنند. این رفتار در مقایسه با نسخه‌های پیشین معکوس شده است. از این گزینه برای نمایش هشدارهای سریالی‌سازی استفاده کنید، که به مستندسازی مناسب فیلدهای سریالی‌پذیر پیش‌فرض و متدهای writeExternal کمک می‌کند.

-charset name

مجموعه‌نویسهٔ (character set) زبان HTML را برای این سند مشخص می‌کند. نام باید یک نام ترجیحی MIME باشد، همان‌طور که در ثبت‌نامهٔ IANA، مجموعه‌نویسه‌ها در http://www.iana.org/assignments/character-sets مشخص شده است.

برای مثال، javadoc -charset "iso-8859-1" mypackage خط زیر را در بخش head هر صفحهٔ تولیدشده درج می‌کند:

<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">

این برچسب META در استاندارد HTML (۴۱۹۷۲۶۵ و ۴۱۳۷۳۲۱)، HTML Document Representation، در آدرس http://www.w3.org/TR/REC-html40/charset.html#h-5.2.2 شرح داده شده است.

همچنین گزینه‌های -encoding و -docencoding name را ببینید.

-docencoding name

کدگذاری (encoding) فایل‌های HTML تولیدشده را مشخص می‌کند. نام باید یک نام ترجیحی MIME باشد، همان‌طور که در ثبت‌نامهٔ IANA، مجموعه‌نویسه‌ها در http://www.iana.org/assignments/character-sets مشخص شده است.

اگر گزینهٔ -docencoding را نادیده بگیرید اما از گزینهٔ -encoding استفاده کنید، کدگذاری فایل‌های HTML تولیدشده توسط گزینهٔ -encoding تعیین می‌شود، برای مثال: javadoc -docencoding "iso-8859-1" mypackage. همچنین گزینه‌های -encoding و -docencoding name را ببینید.

-keywords

برچسب‌های کلیدواژهٔ <META> در HTML را به فایل تولیدشده برای هر کلاس اضافه می‌کند. این برچسب‌ها می‌توانند به موتورهای جستجویی که به دنبال برچسب‌های <META> می‌گردند در یافتن صفحات کمک کنند. بیشتر موتورهای جستجویی که کل اینترنت را جستجو می‌کنند، به برچسب‌های <META> توجهی نمی‌کنند، زیرا صفحات ممکن است از آن‌ها سوءاستفاده کنند. موتورهای جستجوی ارائه‌شده توسط شرکت‌هایی که جستجوی خود را به وب‌سایت خودشان محدود می‌کنند، می‌توانند با بررسی برچسب‌های <META> بهره‌مند شوند. برچسب‌های <META> شامل نام کامل واجد شرایط (fully qualified) کلاس و نام‌های غیرواجد شرایط فیلدها و متدها هستند. سازنده‌ها (constructors) گنجانده نمی‌شوند زیرا با نام کلاس یکسان هستند. برای مثال، کلاس String با این کلیدواژه‌ها آغاز می‌شود:

<META NAME="keywords" CONTENT="java.lang.String class">

<META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">

<META NAME="keywords" CONTENT="length()">

<META NAME="keywords" CONTENT="charAt()">

-tag tagname:Xaoptcmf:"taghead"

دستور javadoc را قادر می‌سازد تا یک برچسب بلوکی سفارشی ساده و تک‌آرگومانی @tagname را در یادداشت‌های مستندسازی تفسیر کند. برای اینکه دستور javadoc بتواند املای نام برچسب‌ها را بررسی کند، مهم است که برای هر برچسب سفارشی موجود در کد مبدأ یک گزینهٔ -tag درج کنید و آن‌هایی را که در اجرای فعلی خروجی داده نمی‌شوند غیرفعال کنید (با X). دونقطه (:) همواره به عنوان جداکننده عمل می‌کند. گزینهٔ -tag سربرگ برچسب taghead را به صورت برجسته (bold) خروجی می‌دهد که در خط بعدی متنِ تک‌آرگومان آن قرار می‌گیرد. مانند هر برچسب بلوکی دیگر، متن آرگومان می‌تواند حاوی برچسب‌های درون‌خطی باشد که آن‌ها نیز تفسیر می‌شوند. خروجی شبیه به برچسب‌های استاندارد تک‌آرگومانی، مانند برچسب‌های @return و @author است. حذف مقداری برای taghead باعث می‌شود tagname به عنوان سربرگ قرار گیرد.

جای‌گذاری برچسب‌ها: آرگومان‌های Xaoptcmf مشخص می‌کنند که برچسب در کجای کد مبدأ مجاز به قرارگیری است و آیا می‌توان برچسب را غیرفعال کرد (با استفاده از X) یا خیر. می‌توانید a را برای مجاز کردن برچسب در همهٔ مکان‌ها، یا هر ترکیبی از حروف دیگر را مشخص کنید:

X (غیرفعال کردن برچسب)

a (همه)

o (نمای کلی)

p (بسته‌ها)

t (نوع‌ها، یعنی کلاس‌ها و رابط‌ها)

c (سازنده‌ها)

m (متدها)

f (فیلدها)

نمونه‌هایی از برچسب‌های منفرد: نمونه‌ای از یک گزینهٔ برچسب برای برچسبی که می‌تواند در هر کجای کد مبدأ استفاده شود عبارت است از: -tag todo:a:"To Do:".

اگر می‌خواهید برچسب @todo فقط با سازنده‌ها، متدها و فیلدها استفاده شود، از این عبارت استفاده می‌کنید: -tag todo:cmf:"To Do:".

توجه داشته باشید که آخرین دونقطه (:) یک جداکنندهٔ پارامتر نیست، بلکه بخشی از متن سربرگ است. شما می‌توانید از هر یک از این گزینه‌های برچسب برای کدهای مبدئی که حاوی برچسب @todo هستند استفاده کنید، مانند: @todo The documentation for this method needs work.

علامت دونقطه در نام برچسب‌ها: برای گریز از دونقطه‌ای (escape) که می‌خواهید در نام یک برچسب استفاده کنید، از یک بک‌اسلش استفاده نمایید. از گزینهٔ -tag ejb\\:bean:a:"EJB Bean:" برای یادداشت مستندسازی زیر استفاده کنید:

/**

 * @ejb:bean

 */

بررسی املای نام برچسب‌ها: برخی از توسعه‌دهندگان برچسب‌های سفارشی را در کد مبدأ قرار می‌دهند که همیشه مایل به چاپ آن‌ها در خروجی نیستند. در این موارد، مهم است که تمام برچسب‌های موجود در کد مبدأ را فهرست کنید، برچسب‌هایی را که می‌خواهید در خروجی ظاهر شوند فعال کرده و آن‌هایی را که نمی‌خواهید غیرفعال نمایید. وجود X برچسب را غیرفعال می‌کند، در حالی که عدم وجود آن برچسب را فعال می‌سازد. این کار اطلاعات کافی را در اختیار دستور javadoc قرار می‌دهد تا بداند آیا برچسبی که با آن مواجه شده ناشناخته است (که احتمالاً نتیجهٔ یک خطای تایپی یا املای نادرست است) یا خیر. دستور javadoc در این موارد یک هشدار چاپ می‌کند. می‌توانید X را به مقادیر جای‌گذاری که از قبل موجودند اضافه کنید، به طوری که هر زمان خواستید برچسب را فعال کنید، به سادگی X را حذف نمایید. برای مثال، اگر برچسب @todo برچسبی است که می‌خواهید از خروجی حذف شود، می‌توانید از این عبارت استفاده کنید: -tag todo:Xcmf:"To Do:". اگر ترجیح می‌دهید آن را ساده نگه دارید، از این دستور استفاده کنید: -tag todo:X. نحو -tag todo:X حتی زمانی که برچسب @todo توسط یک taglet تعریف شده باشد نیز کار می‌کند.

ترتیب برچسب‌ها: ترتیب گزینه‌های -tag و -taglet ترتیب خروجی برچسب‌ها را تعیین می‌کند. می‌توانید برچسب‌های سفارشی را با برچسب‌های استاندارد ترکیب کنید تا در میان آن‌ها پراکنده شوند. گزینه‌های برچسب برای برچسب‌های استاندارد صرفاً جای‌نگه‌دار (placeholder) برای تعیین ترتیب هستند. آن‌ها فقط نام برچسب استاندارد را می‌پذیرند. زیرعنوان‌های برچسب‌های استاندارد قابل تغییر نیستند. این موضوع در مثال زیر نشان داده شده است. اگر گزینهٔ -tag موجود نباشد، موقعیت گزینهٔ -taglet ترتیب آن را مشخص می‌کند. اگر هر دو حضور داشته باشند، هر کدام که در خط فرمان در جایگاه آخر قرار گیرد ترتیب را مشخص می‌کند. این به این دلیل است که برچسب‌ها و tagletها به ترتیبی که در خط فرمان ظاهر می‌شوند پردازش می‌گردند. برای مثال، اگر گزینه‌های -taglet و -tag دارای مقدار نام todo باشند، آن گزینه‌ای که در آخر خط فرمان قرار دارد ترتیب را مشخص می‌کند.

نمونه‌ای از یک مجموعهٔ کامل برچسب‌ها: این مثال عبارت To Do را بعد از Parameters و قبل از Throws در خروجی درج می‌کند. با استفاده از X، همچنین مشخص می‌کند که ممکن است با برچسب @example در کد مبدأ مواجه شود که نباید در این اجرا خروجی داده شود. اگر از برچسب @argfile استفاده کنید، می‌توانید برچسب‌ها را در خطوط جداگانه در یک فایل آرگومان مشابه این قرار دهید (نیازی به نویسه‌های ادامه‌دهندهٔ خط نیست):

-tag param

-tag return

-tag todo:a:"To Do:"

-tag throws

-tag see

-tag example:X

هنگامی که دستور javadoc یادداشت‌های مستندسازی را تجزیه می‌کند، هر برچسبی که با آن مواجه شود و نه برچسب استاندارد باشد و نه از طریق گزینه‌های -tag یا -taglet ارسال شده باشد، ناشناخته تلقی شده و یک هشدار صادر می‌شود.

برچسب‌های استاندارد ابتدا در یک فهرست داخلی با ترتیب پیش‌فرض خود ذخیره می‌شوند. هر زمان که گزینه‌های -tag استفاده شوند، آن برچسب‌ها به انتهای این فهرست اضافه می‌شوند. برچسب‌های استاندارد از موقعیت پیش‌فرض خود جابه‌جا می‌شوند. بنابراین، اگر گزینهٔ -tag برای یک برچسب استاندارد نادیده گرفته شود، آن برچسب در موقعیت پیش‌فرض خود باقی می‌ماند.

جلوگیری از تداخل: اگر می‌خواهید فضای نام (namespace) اختصاصی خود را بسازید، می‌توانید از شیوهٔ نام‌گذاریِ تفکیک‌شده با نقطه، مشابه آنچه برای بسته‌ها به کار می‌رود، استفاده کنید: com.mycompany.todo. شرکت Oracle به ایجاد برچسب‌های استانداردی که نام آن‌ها حاوی نقطه نیست ادامه خواهد داد. هر برچسبی که ایجاد کنید رفتار برچسبی با همان نام را که توسط Oracle تعریف شده است لغو (override) می‌کند. اگر یک برچسب یا taglet به نام @todo بسازید، حتی در صورتی که بعداً Oracle برچسب استانداردی با همین نام بسازد، همواره همان رفتاری را خواهد داشت که شما تعریف کرده‌اید.

حاشیه‌نویسی‌ها در برابر برچسب‌های Javadoc: به‌طور کلی، اگر نشانه‌گذاری مورد نظری که می‌خواهید اضافه کنید قرار است بر مستندات تأثیر بگذارد یا آن را تولید کند، باید یک برچسب Javadoc باشد. در غیر این صورت، باید یک حاشیه‌نویسی (annotation) باشد. به بخش Custom Tags and Annotations در How to Write Doc Comments for the Javadoc Tool در آدرس http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#annotations مراجعه کنید.

همچنین می‌توانید با گزینهٔ -taglet برچسب‌های بلوکی پیچیده‌تر یا برچسب‌های درون‌خطی سفارشی ایجاد کنید..TP -taglet class
فایل کلاسی را مشخص می‌کند که تگ‌لت (taglet) مورد استفاده در تولید مستندات برای آن تگ را آغاز می‌نماید. برای مقدار class از نام کامل و واجد شرایط (fully qualified name) استفاده کنید. این تگ‌لت همچنین تعداد آرگومان‌های متنی را که تگ سفارشی دارد مشخص می‌کند. تگ‌لت این آرگومان‌ها را می‌پذیرد، آن‌ها را پردازش می‌کند و خروجی را تولید می‌نماید. برای مستندات جامع به همراه نمونه‌های تگ‌لت، به بخش Taglet Overview در نشانی http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/taglet/overview.html مراجعه کنید.

تگ‌لت‌ها برای تگ‌های بلوکی یا درون‌خطی (inline) مفید هستند. آن‌ها می‌توانند هر تعداد آرگومان داشته باشند و رفتارهای سفارشی را پیاده‌سازی کنند، مانند پررنگ (bold) کردن متن، قالب‌بندی بالت‌ها، نوشتن متن در یک فایل، یا آغاز فرایندهای دیگر. تگ‌لت‌ها تنها می‌توانند تعیین کنند که یک تگ کجا و با چه قالبی ظاهر شود. تمام تصمیمات دیگر توسط doclet گرفته می‌شود. یک تگ‌لت نمی‌تواند کارهایی مانند حذف یک نام کلاس از فهرست کلاس‌های گنجانده‌شده را انجام دهد. با این حال، می‌تواند اثرات جانبی (side effects) را اجرا کند، مانند چاپ متن تگ در یک فایل یا راه‌اندازی فرایندی دیگر. از گزینهٔ -tagletpath برای مشخص کردن مسیر تگ‌لت استفاده کنید. مثال زیر تگ‌لت To Do را بعد از Parameters و قبل از Throws در صفحات تولیدشده درج می‌کند. به عنوان روش جایگزین، می‌توانید از گزینهٔ -taglet به جای گزینهٔ -tag آن استفاده کنید، اما خواندن آن ممکن است دشوار باشد.

-taglet com.sun.tools.doclets.ToDoTaglet

-tagletpath /home/taglets 

-tag return

-tag param

-tag todo

-tag throws

-tag see

-tagletpath tagletpathlist

مسیرهای جستجو را برای یافتن فایل‌های کلاس تگ‌لت مشخص می‌کند. مقدار tagletpathlist می‌تواند شامل چند مسیر باشد که با دونقطه (:) از یکدیگر جدا شده‌اند. دستور javadoc تمام زیردایرکتوری‌های مسیرهای مشخص‌شده را جستجو می‌کند.

-docfilesubdirs

رونوشت‌برداری عمیق (deep copying) از دایرکتوری‌های doc-files را فعال می‌کند. زیردایرکتوری‌ها و تمامی محتویات به‌صورت بازگشتی در مقصد کپی می‌شوند. برای مثال، دایرکتوری doc-files/example/images و تمام محتویات آن کپی خواهند شد. همچنین گزینه‌ای برای استثنا کردن زیردایرکتوری‌ها وجود دارد.

-excludedocfilessubdir name1:name2

هر یک از زیردایرکتوری‌های doc-files با نام‌های مشخص‌شده را استثنا می‌کند. این کار از کپی شدن زیردایرکتوری‌های SCCS و سایر دایرکتوری‌های سیستم کنترل کد منبع جلوگیری می‌کند.

-noqualifier all | packagename1:packagename2...

نام‌های توصیف‌کنندهٔ بسته (qualifying package names) را از نام کلاس‌ها در خروجی حذف می‌کند. آرگومان گزینهٔ -noqualifier یا all است (همهٔ توصیف‌کننده‌های بسته حذف می‌شوند) یا فهرستی از بسته‌ها که با دونقطه از هم جدا شده‌اند، به همراه کاراکترهای عمومی (wildcards)، که باید به عنوان توصیف‌کننده حذف شوند. نام بسته از جاهایی که نام کلاس یا واسط ظاهر می‌شود حذف می‌گردد. بخش Process Source Files را ببینید.

مثال زیر تمام توصیف‌کننده‌های بسته را حذف می‌کند: -noqualifier all.

مثال زیر توصیف‌کننده‌های بستهٔ java.lang و java.io را حذف می‌کند: -noqualifier java.lang:java.io.

مثال زیر توصیف‌کننده‌های بسته‌ای را که با java شروع می‌شوند و زیربسته‌های com.sun را حذف می‌کند، اما javax را حذف نمی‌کند: -noqualifier java.*:com.sun.*.

در جاهایی که یک توصیف‌کنندهٔ بسته طبق رفتار پیشین ظاهر می‌شد، نام می‌تواند به شکل مناسب کوتاه شود. بخش How a Name Appears را ببینید. این قاعده چه از گزینهٔ -noqualifier استفاده شود و چه نشود اعمال می‌گردد.

-notimestamp

برچسب زمانی (time stamp) را که در یک کامنت HTML در بالای هر صفحه از HTMLهای تولیدشده پنهان است، غیرفعال می‌کند. گزینهٔ -notimestamp زمانی مفید است که می‌خواهید دستور javadoc را روی دو پایگاه کد منبع اجرا کرده و تفاوت‌های بین آن‌ها را با diff به دست آورید، زیرا از این که برچسب‌های زمانی باعث ایجاد تفاوت در خروجی diff شوند جلوگیری می‌کند (که در غیر این صورت در هر صفحه یک diff ایجاد می‌شد). برچسب زمانی شامل شماره انتشار دستور javadoc است و در حال حاضر چیزی شبیه به این ظاهر می‌شود: <!-- Generated by javadoc (build 1.5.0_01) on Thu Apr 02 14:04:52 IST 2009 -->.

-nocomment

کل متن کامنت، شامل توضیحات اصلی و تمام تگ‌ها را نادیده گرفته و تنها اعلان‌ها (declarations) را تولید می‌کند. این گزینه به شما اجازه می‌دهد تا از فایل‌های منبعی که در ابتدا برای هدف دیگری در نظر گرفته شده بودند مجدداً استفاده کنید تا بتوانید در مراحل اولیه یک پروژه جدید، اسکلت مستندات HTML را تولید نمایید.

-sourcetab tablength

تعداد فاصله‌هایی (spaces) را که هر تب در سورس استفاده می‌کند مشخص می‌نماید.

مثال‌های ساده (SIMPLE EXAMPLES)

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

در مثال‌های زیر، فایل‌های سورس در /home/src/java/awt/*.java قرار دارند. دایرکتوری مقصد /home/html است.

مستندسازی یک یا چند بسته

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

اگر نام یک بسته دارای چندین شناسه باشد (که با نقطه جدا شده‌اند، مانند java.awt.color)، در این صورت هر شناسهٔ بعدی باید با یک زیردایرکتوری عمیق‌تر متناظر باشد (مانند java/awt/color).

تا زمانی که -sourcepath به هر دو درخت اشاره کند، می‌توانید فایل‌های سورس یک بستهٔ واحد را بین دو درخت دایرکتوری واقع در مکان‌های مختلف تقسیم کنید. برای مثال، src1/java/awt/color و src2/java/awt/color.

می‌توانید دستور javadoc را یا با تغییر دایرکتوری (با دستور cd) یا با استفاده از گزینهٔ -sourcepath اجرا کنید. مثال‌های زیر هر دو روش را نشان می‌دهند.

مثال ۱: اجرای بازگشتی از یک یا چند بسته

این مثال از -sourcepath استفاده می‌کند تا دستور javadoc بتواند از هر دایرکتوری اجرا شود، و از -subpackages (گزینه‌ای جدید در نسخهٔ 1.4) برای اجرای بازگشتی بهره می‌برد. این دستور زیربسته‌های دایرکتوری java را پیمایش می‌کند، به استثنای بسته‌هایی که ریشه در java.net و java.lang دارند. توجه داشته باشید که این کار java.lang.ref را که زیربسته‌ای از java.lang است مستثنی می‌کند. برای پیمایش سایر درخت‌های بسته نیز می‌توانید نام آن‌ها را به آرگومان -subpackages اضافه کنید، مانند java:javax:org.xml.sax.

javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude

مثال ۲: تغییر به دایرکتوری ریشه و اجرای بسته‌های صریح

به دایرکتوری والدِ بستهٔ کاملاً مشخص‌شده (fully qualified) بروید. سپس دستور javadoc را با نام یک یا چند بسته‌ای که می‌خواهید مستندسازی کنید اجرا نمایید:

cd /home/src/

javadoc -d /home/html java.awt java.awt.event

برای پیمایش سایر درخت‌های بسته نیز نام آن‌ها را به آرگومان -subpackages پیوست کنید، مانند java:javax:org.xml.sax.

مثال ۳: اجرا از هر دایرکتوری روی بسته‌های صریح در یک درخت

در این حالت، اهمیتی ندارد که دایرکتوری فعلی چه باشد. دستور javadoc را اجرا کرده و از گزینهٔ -sourcepath به همراه دایرکتوری والدِ بستهٔ سطح بالا (top-level) استفاده کنید. نام یک یا چند بسته‌ای را که می‌خواهید مستندسازی کنید مشخص نمایید:

javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event

مثال ۴: اجرا از هر دایرکتوری روی بسته‌های صریح در چندین درخت

دستور javadoc را اجرا کرده و از گزینهٔ -sourcepath همراه با فهرستی از مسیرهای ریشهٔ هر درخت که با دونقطه (:) جدا شده‌اند استفاده نمایید. نام یک یا چند بسته‌ای را که می‌خواهید مستندسازی کنید مشخص کنید. نیازی نیست تمام فایل‌های سورس یک بستهٔ مشخص در یک دایرکتوری ریشهٔ واحد قرار داشته باشند، اما باید در جایی در طول مسیر سورس (source path) پیدا شوند.

javadoc -d /home/html -sourcepath /home/src1:/home/src2 java.awt java.awt.event

نتیجه این است که تمام حالت‌ها مستنداتی با ساختار HTML برای کلاس‌ها و رابط‌های public و protected در بسته‌های java.awt و java.awt.event تولید کرده و فایل‌های HTML را در دایرکتوری مقصدِ مشخص‌شده ذخیره می‌کنند. از آنجا که دو یا چند بسته در حال تولید هستند، سند دارای سه قاب (frame) تحت HTML خواهد بود: یکی برای فهرست بسته‌ها، دیگری برای فهرست کلاس‌ها، و سومی برای صفحات اصلی کلاس‌ها.

مستندسازی یک یا چند کلاس

روش دوم برای اجرای دستور javadoc، ارسال یک یا چند فایل سورس است. می‌توانید javadoc را به یکی از دو روش زیر اجرا کنید: با تغییر دایرکتوری (با دستور cd) یا با مشخص کردن کامل مسیر فایل‌های سورس. مسیرهای نسبی نسبت به دایرکتوری فعلی سنجیده می‌شوند. هنگام ارسال فایل‌های سورس، گزینهٔ -sourcepath نادیده گرفته می‌شود. برای تعیین گروهی از کلاس‌ها می‌توانید از نویسه‌های عام خط فرمان، مانند ستاره (*)، استفاده کنید.

مثال ۱: تغییر به دایرکتوری سورس

به دایرکتوری حاوی فایل‌های سورس بروید. سپس دستور javadoc را با نام یک یا چند فایل سورسی که می‌خواهید مستندسازی کنید اجرا نمایید.

این مثال مستنداتی با ساختار HTML برای کلاس‌های Button، Canvas و کلاس‌هایی که با Graphics آغاز می‌شوند تولید می‌کند. از آنجا که به‌جای نام بسته‌ها، فایل‌های سورس به عنوان آرگومان به دستور javadoc داده شده‌اند، سند دارای دو قاب خواهد بود: یکی برای فهرست کلاس‌ها و دیگری برای صفحهٔ اصلی.

cd /home/src/java/awt

javadoc -d /home/html Button.java Canvas.java Graphics*.java

مثال ۲: تغییر به دایرکتوری ریشهٔ بسته

این روش برای مستندسازی فایل‌های سورس منفرد از زیربسته‌های مختلف که ریشهٔ یکسانی دارند مفید است. به دایرکتوری ریشهٔ بسته بروید و فایل‌های سورس را همراه با مسیرشان از ریشه مشخص نمایید.

cd /home/src/

javadoc -d /home/html java/awt/Button.java java/applet/Applet.java

مثال ۳: مستندسازی فایل‌ها از هر دایرکتوری

در این حالت، اهمیتی ندارد که دایرکتوری فعلی چه باشد. دستور javadoc را با مسیر مطلق (یا مسیر نسبی به دایرکتوری فعلی) فایل‌های سورسی که می‌خواهید مستندسازی کنید اجرا نمایید.

javadoc -d /home/html /home/src/java/awt/Button.java

/home/src/java/awt/Graphics*.java

مستندسازی بسته‌ها و کلاس‌ها

می‌توانید کل بسته‌ها و کلاس‌های منفرد را به طور هم‌زمان مستندسازی کنید. در اینجا مثالی ارائه شده که دو مورد از مثال‌های پیشین را ترکیب می‌کند. می‌توانید از گزینهٔ -sourcepath برای مسیر بسته‌ها استفاده کنید اما نه برای مسیر کلاس‌های منفرد.

javadoc -d /home/html -sourcepath /home/src java.awt

/home/src/java/applet/Applet.java

مثال خط فرمان

دستور زیر ممکن است برای برخی از شل‌ها بیش از حد طولانی باشد. برای غلبه بر این محدودیت می‌توانید از یک فایل آرگومان خط فرمان استفاده کنید (یا یک اسکریپت شل بنویسید).

در این مثال، packages نام فایلی است که بسته‌های مورد پردازش، مانند java.appletjava.lang را در بر دارد. هیچ‌یک از گزینه‌ها نباید شامل نویسه خط جدید بین علامت‌های نقل‌قول تکی باشد. برای مثال، اگر این نمونه را رونوشت و جای‌گذاری می‌کنید، نویسه‌های خط جدید را از گزینه -bottom حذف کنید.

javadoc -sourcepath /java/jdk/src/share/classes \

-overview /java/jdk/src/share/classes/overview.html \

-d /java/jdk/build/api \

-use \

-splitIndex \

-windowtitle 'Java Platform, Standard Edition 7 API Specification' \

-doctitle 'Java Platform, Standard Edition 7 API Specification' \

-header '<b>Java™ SE 7</b>' \

-bottom '<font size="-1">

<a href="http://bugreport.sun.com/bugreport">Submit a bug or feature</a><br/>

Copyright &copy; 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>

Oracle is a registered trademark of Oracle Corporation and/or its affiliates.

Other names may be trademarks of their respective owners.</font>' \

-group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \

-group "Extension Packages" "javax.*" \

-J-Xmx180m \  

@packages

رابط برنامه‌نویسی

رابط Javadoc Access API کاربر را قادر می‌سازد تا ابزار Javadoc را مستقیماً از یک برنامه Java و بدون اجرای یک پردازش جدید فراخوانی کند.

برای مثال، عبارت‌های زیر معادل دستور javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude java.net:java.lang com.example هستند:

import javax.tools.DocumentationTool;

import javax.tools.ToolProvider;

public class JavaAccessSample{

    public static void main(String[] args){

        DocumentationTool javadoc = ToolProvider.getSystemDocumentationTool();

        int rc = javadoc.run( null, null, null,

                 "-d", "/home/html",

                 "-sourcepath", "home/src",

                 "-subpackages", "java",

                 "-exclude", "java.net:java.lang",

                 "com.example");

     }

 }

سه آرگومان نخست متد run، جریان‌های ورودی، خروجی استاندارد و خطای استاندارد را مشخص می‌کنند. مقدار پیش‌فرض برای هر یک از System.in، System.out و System.err به ترتیب برابر با Null است.

مثال MAKEFILE (THE MAKEFILE EXAMPLE)

این یک نمونه از یک makefile در GNU است. علامت‌های نقل‌قول تکی دور آرگومان‌های makefile قرار می‌گیرند. برای دیدن یک مثال از makefile ویندوز، بخش makefiles از Javadoc FAQ را در http://www.oracle.com/technetwork/java/javase/documentation/index-137483.html#makefiles ببینید.

javadoc -sourcepath $(SRCDIR)              \   /* Sets path for source files   */

        -overview $(SRCDIR)/overview.html  \   /* Sets file for overview text  */

        -d /java/jdk/build/api             \   /* Sets destination directory   */

        -use                               \   /* Adds "Use" files             */

        -splitIndex                        \   /* Splits index A-Z             */

        -windowtitle $(WINDOWTITLE)        \   /* Adds a window title          */

        -doctitle $(DOCTITLE)              \   /* Adds a doc title             */

        -header $(HEADER)                  \   /* Adds running header text     */

        -bottom $(BOTTOM)                  \   /* Adds text at bottom          */

        -group $(GROUPCORE)                \   /* 1st subhead on overview page */

        -group $(GROUPEXT)                 \   /* 2nd subhead on overview page */

        -J-Xmx180m                         \   /* Sets memory to 180MB         */

        java.lang java.lang.reflect        \   /* Sets packages to document    */

        java.util java.io java.net         \

        java.applet

WINDOWTITLE = 'Java™ SE 7 API Specification'

DOCTITLE = 'Java™ Platform Standard Edition 7 API Specification'

HEADER = '<b>Java™ SE 7</font>'

BOTTOM = '<font size="-1">

      <a href="http://bugreport.sun.com/bugreport">Submit a bug or feature</a><br/>

      Copyright &copy; 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>

      Oracle is a registered trademark of Oracle Corporation and/or its affiliates.

      Other names may be trademarks of their respective owners.</font>'

GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'

GROUPEXT  = '"Extension Packages" "javax.*"'

SRCDIR = '/java/jdk/1.7.0/src/share/classes'

•

اگر گزینهٔ -windowtitle را نادیده بگیرید، دستور javadoc عنوان سند را در عنوان پنجره کپی می‌کند. متن گزینهٔ -windowtitle شبیه به گزینهٔ -doctitle است، اما بدون برچسب‌های HTML تا از نمایش این برچسب‌ها به صورت متن خام در عنوان پنجره جلوگیری شود.

•

اگر گزینهٔ -footer را نادیده بگیرید، دستور javadoc متن سربرگ را در پانویس کپی می‌کند.

•

گزینه‌های مهم دیگری که ممکن است بخواهید استفاده کنید اما در مثال قبلی نیازی به آن‌ها نبود، گزینه‌های -classpath و -link هستند.