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

دستور javadoc فایل‌هایی را که به منبع ختم می‌شوند و سایر فایل‌های توصیف‌شده در «فایل‌های منبع» را پردازش می‌کند. اگر دستور javadoc را با ارسال جداگانه نام فایل‌های منبع اجرا کنید، می‌توانید دقیقاً مشخص کنید که چه فایل‌های منبعی پردازش شوند. با این حال، بیشتر توسعه‌دهندگان مایل به این شیوه کار نیستند، چرا که ارسال نام بسته‌ها ساده‌تر است. دستور javadoc را می‌توان به سه روش بدون تعیین صریح نام فایل‌های منبع اجرا کرد: می‌توانید نام بسته‌ها را ارسال کنید، از گزینه -subpackages استفاده نمایید، یا از نویسه‌های عام همراه با نام فایل‌های منبع بهره بگیرید. در این حالت‌ها، دستور javadoc یک فایل منبع را تنها زمانی پردازش می‌کند که فایل تمام شرایط زیر را برآورده سازد:

•

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

•

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

•

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

پردازش پیوندها

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

•

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

•

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

•

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

•

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

•

پیوندهای Specified by به اعضای رابط و پیوندهای Overrides به اعضای کلاس. به بخش توارث کامنت متد مراجعه کنید.

•

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

•

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

•

نمایه (index).

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

جزئیات پردازش

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

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

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

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

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

هنگامی که دستور javadoc ساختار درونی خود را برای مستندات می‌سازد، تمام کلاس‌های ارجاع داده شده را بارگذاری می‌کند. به همین دلیل، دستور javadoc باید بتواند تمام کلاس‌های ارجاع داده شده را بیابد، چه کلاس‌های راه‌اندازی (bootstrap)، افزونه‌ها، یا کلاس‌های کاربر. بخش «چگونگی یافتن کلاس‌ها» را در http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html ببینید.

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

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

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

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

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

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

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

•

فایل package-info.java می‌تواند شامل اعلان بسته، حاشیه‌نویسی‌های (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) باشد.

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

هنگامی که دستور 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)" هر برنامه یا مجموعه‌ای از بسته‌ها که مستندسازی می‌کنید می‌تواند یادداشت توضیحی (کامنت) نمای کلیِ ویژه خود را داشته باشد که در فایل سورس جداگانه‌ای نگهداری می‌شود و دستور javadoc آن را در صفحه نمای کلی تولیدشده ادغام می‌کند. معمولاً در این توضیحات، هرگونه مستنداتی را که به کل برنامه یا مجموعه بسته‌ها اعمال می‌شود، قرار می‌دهید.

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

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

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

محتوای فایل توضیحات نمای کلی، یک کامنت مستندسازی بزرگ است که به زبان HTML نوشته می‌شود. جمله اول را به خلاصه‌ای درباره برنامه یا مجموعه بسته‌ها اختصاص دهید. بین تگ <body> و جمله اول، هیچ عنوان یا متن دیگری قرار ندهید. تمام تگ‌ها به جز تگ‌های درون‌خطی (inline)، مانند تگ {@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 به دایرکتوری مقصد کپی کند. این فایل‌ها معمولاً شامل فایل‌های گرافیکی، فایل‌های نمونه سورس و کلاس جاوا، و فایل‌های 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 مشخص شده را می‌گنجاند. صفحه نمای کلی تنها زمانی ایجاد می‌شود که دو یا چند نام بسته را به دستور javadoc ارسال کنید. بخش‌های فریم‌های HTML و گزینه‌ها را ببینید.

صفحه‌های ارجاع متقابل (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) که اطلاعاتی درباره کلاس‌های سریال‌پذیر (serializable) و اکسترنال‌پذیر (externalizable) به همراه توضیحات فیلدها و متدها ارائه می‌دهد. اطلاعات این صفحه برای بازپیاده‌سازی‌کنندگان مفید است و نه برای توسعه‌دهندگانی که می‌خواهند از API استفاده کنند. برای دسترسی به صفحه فرم سریالی‌شده، به هر کلاس سریالی‌شده رفته و روی Serialized Form در بخش See Also کامنت کلاس کلیک کنید. داکلت استاندارد صفحه‌ای از فرم سریالی‌شده تولید می‌کند که هر کلاسی (عمومی یا غیرعمومی) را که Serializable را پیاده‌سازی کرده به همراه متدهای readObject و writeObject آن، فیلدهایی که سریال‌سازی می‌شوند و کامنت‌های مستندسازیِ تگ‌های @serial، @serialField و @serialData فهرست می‌کند. کلاس‌های سریال‌پذیر عمومی را می‌توان با علامت‌گذاری آن‌ها (یا بسته‌شان) با @serial exclude مستثنی کرد، و کلاس‌های سریال‌پذیر با سطح دسترسی بسته (package-private) را می‌توان با علامت‌گذاری با @serial include شامل نمود. از نگارش 1.4 به بعد، می‌توانید با اجرای دستور javadoc بدون مشخص کردن گزینه -private، فرم سریالی‌شده کامل را برای کلاس‌های عمومی و خصوصی تولید کنید. بخش گزینه‌ها را ببینید.

•

یک صفحه نمایه (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) تولیدشده در همان سلسله‌مراتب دایرکتوری‌ای سازمان‌دهی می‌شوند که فایل‌های منبع و فایل‌های کلاس Java سازمان‌دهی شده‌اند. این ساختار شامل یک دایرکتوری به ازای هر زیربسته است.

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

با این فرض که نام دایرکتوری مقصد apidocs باشد، ساختار فایل برای بسته java.applet در ادامه آمده است. همان‌طور که اشاره شد، تمام فایل‌هایی که حاوی کلمه 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) کامنت‌های مستندسازی ایجاد کنید، هرچند ساختار دستوری آن‌ها کمی متفاوت است. یک کامنت مستندسازی از نویسه‌های میان /** و */ پایانی تشکیل شده است. وجود ستاره‌های ابتدایی در هر سطر مجاز است و در بخش بعد بیشتر توضیح داده شده است. متن درون یک کامنت می‌تواند در چند سطر ادامه یابد.

/**

 * 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)

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

/**

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

 * @see java.lang.Object

 */

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

برچسب، یک کلمهٔ کلیدی ویژه درون کامنت مستندسازی است که توسط دستور javadoc پردازش می‌شود. دو نوع برچسب وجود دارد: برچسب‌های بلوکی (block tags) که به صورت برچسب @tag ظاهر می‌شوند (همچنین به عنوان برچسب‌های مستقل یا standalone شناخته می‌شوند)، و برچسب‌های درون‌خطی (inline tags) که درون آکولادها به شکل برچسب {@tag} ظاهر می‌گردند. برای اینکه یک برچسب بلوکی تفسیر شود، باید در ابتدای یک سطر قرار گیرد (با نادیده گرفتن ستاره‌های ابتدایی، فاصله‌های خالی و جداکنندهٔ /**). این بدان معناست که می‌توانید از نویسهٔ @ در جاهای دیگر متن استفاده کنید و به عنوان آغاز یک برچسب تفسیر نخواهد شد. اگر می‌خواهید سطری را با نویسهٔ @ آغاز کنید و نمی‌خواهید تفسیر شود، از نهاد اچ‌تی‌ام‌ال (HTML entity) &#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 که مرورگرتان پشتیبانی می‌کند استفاده کنید. داکلت استاندارد (standard doclet) در سایر قسمت‌ها (خارج از کامنت‌های مستندسازی) کدی منطبق با HTML 3.2 به همراه شیوه‌نامه‌های آبشاری (CSS) و فریم‌ها تولید می‌کند. برای فایل‌های تولیدشده، نسخهٔ HTML 4.0 به دلیل مجموعه‌فریم‌ها (frame sets) ترجیح داده می‌شود.

برای نمونه، نهادها برای نماد کوچک‌تر از (<) و نماد بزرگ‌تر از (>) باید به صورت &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)

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

/** 

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

 */

public int x, y;      // Avoid this 

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

public int x

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

public int y

The horizontal and vertical distances of point (x, y)..PP استفاده از برچسب‌های سربرگ (Use of Header Tags)

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

وراثت توضیحات متد (METHOD COMMENT INHERITANCE)

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

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

تکمیل متن‌های جاافتاده (Fill in Missing Text)

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

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

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

بخش برچسب‌ها و گزینه‌های Javadoc (Javadoc Tags and Options) را ببینید.

وراثت صریح (Explicit Inheritance)

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

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

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

•

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

•

زمانی که یک متد در یک رابط، متدی را در یک سوپررابط بازنویسی می‌کند

•

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

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

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

الگوریتم توضیحات متد (METHOD COMMENTS ALGORITHM)

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

1.

در هر رابط مستقیماً پیاده‌سازی‌شده (یا ارث‌بری‌شده)، به ترتیبی که پس از کلمه 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>.

متن را با قلم کد بدون تفسیر متن به عنوان نشانه‌گذاری 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 را قبل از توضیحات اصلی قرار می‌دهد، آن را با قلم کج (italic) می‌آورد و هشداری پررنگ با عنوان Deprecated پیش از آن درج می‌کند. این برچسب در تمام یادداشت‌های مستندسازی معتبر است: overview، بسته، کلاس، رابط، سازنده، متد و فیلد.

جمله اولِ متنِ منسوخ‌شدن باید به کاربر بگوید که این API در چه زمانی منسوخ شده و چه چیزی باید به عنوان جایگزین آن استفاده شود. دستور javadoc جمله اول را در بخش خلاصه و نمایه کپی می‌کند. جملات بعدی نیز می‌توانند دلیل منسوخ‌شدن را توضیح دهند. شما باید یک برچسب {@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، بسته، کلاس، رابط، سازنده، متد و فیلد، و شامل بخش متنی هر برچسبی (مانند برچسب‌های @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، بسته، کلاس، رابط، سازنده، متد و فیلد، شامل بخش متنی هر برچسب مانند برچسب‌های @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 است. هر دو برچسب به مراجع یکسانی نیاز دارند و نحو یکسانی را برای package.class#member و label می‌پذیرند. تفاوت اصلی در این است که برچسب {@link} به جای قرار دادن پیوند در بخش See Also، یک پیوند درون‌خطی ایجاد می‌کند. برچسب {@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 می‌افزاید. هنگام نوشتن کامنت مستندات، می‌توانید توضیحات را در چند سطر ادامه دهید. این برچسب فقط در کامنت مستندات یک متد، سازنده (constructor) یا کلاس معتبر است. بخش @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) از یک کلاس، متد یا سازنده باشد. برای مشخص کردن استفاده از پارامتر نوع، از براکت‌های شکسته (angle brackets) در دو طرف نام پارامتر استفاده کنید.

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

/**

 * @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، package، class، interface، constructor، method یا field. برای درج یک پیوند درون‌خطی در یک جمله به یک پکیج، کلاس یا عضو، {@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 پیوندی همراه با یک برچسب متنیِ قابل مشاهده می‌افزاید که به مستندات نام مشخص‌شده و ارجاع‌یافته در زبان جاوا اشاره می‌کند. برچسب اختیاری است. در صورت حذف برچسب، نام به عنوان متن قابل مشاهده و به‌طور متناسب خلاصه‌شده نمایش می‌یابد. برای حذف سراسری نام پکیج از این متنِ قابل مشاهده، از گزینهٔ -noqualifier استفاده کنید. زمانی از برچسب استفاده کنید که می‌خواهید متن قابل مشاهده با متن تولیدشدهٔ خودکار متفاوت باشد. بخش How a Name Appears را ببینید.

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

در مثال زیر، یک برچسب @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 می‌تواند کاملاً مشخص‌شده (fully qualified) باشد، مانند java.lang.String#toUpperCase()، یا خیر، مانند String#toUpperCase() یا #toUpperCase(). اگر نام کمتر از حالت کاملاً مشخص‌شده باشد، دستور javadoc از ترتیب جستجوی استاندارد کامپایلر جاوا برای یافتن آن استفاده می‌کند. بخش Search Order for the @see Tag را ببینید. نام می‌تواند در داخل پرانتزها حاوی فضای خالی باشد، مانند فاصله‌های میان آرگومان‌های متد. مزیت ارائهٔ نام‌های کوتاه‌تر و نیمه‌مشخص (partially qualified) این است که تایپ کردن آن‌ها کوتاه‌تر بوده و شلوغی کمتری در کد مبدأ ایجاد می‌شود. فهرست زیر فرم‌های گوناگون نام را نشان می‌دهد، که در آن 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) باید برای تمام قالب‌ها به‌صورت outer.inner مشخص شوند، نه فقط inner.

•

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

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

دستور javadoc برچسب @see را که در یک فایل مبدأ، فایل بسته یا فایل مرور کلی (overview) ظاهر می‌شود، پردازش می‌کند. در دو فایل آخر، باید نامی را که همراه با برچسب @see ارائه می‌دهید، به‌طور کامل واجد شرایط (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 ارجاع دهد، دستور javadoc در آن بسته جستجو نمی‌کند مگر اینکه آن کلاس، بسته مزبور را وارد کرده باشد.

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

اگر 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" 

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

@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 اختیاری باید معنای فیلد را توضیح داده و مقادیر مجاز را فهرست کند. در صورت نیاز، توضیحات می‌تواند چندین خط را در بر گیرد. داک‌لت (doclet) استاندارد این اطلاعات را به صفحه فرمت سریالی‌شده می‌افزاید. بخش «صفحات ارجاع متقابل» را ببینید.

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

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

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

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

@serialData data-description

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

از مقدار شرح داده برای مستندسازی نوع‌ها و ترتیب داده‌ها در فرمت سریالی‌شده استفاده می‌کند. این داده‌ها شامل داده‌های اختیاری نوشته‌شده توسط متد 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 به مستندات تولیدشده می‌افزاید. این متن هیچ ساختار درونی خاصی ندارد. این برچسب در هر کامنت مستندسازی معتبر است: مرور کلی، بسته، کلاس، رابط، سازنده، متد یا فیلد. این برچسب بدین معناست که این تغییر یا ویژگی از زمان انتشار نرم‌افزاری که با مقدار 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 Options را ببینید

•

همچنین بخش Standard Doclet Options را ببینید

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

-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 باید متن مستندات کلی را از فایل مبدأ مشخص‌شده توسط 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>)

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

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

هنگامی که -Xdoclint فعال باشد، مشکلات را با پیام‌هایی مشابه دستور javac گزارش می‌دهد. دستور javadoc یک پیام، رونوشتی از خط مبدأ و یک علامت هشتک (caret) که به موقعیت دقیق شناسایی خطا اشاره دارد را چاپ می‌کند. پیام‌ها بسته به شدت و احتمال ایجاد خطا در صورتی که مستندات تولیدشده توسط یک اعتبارسنج بررسی شوند، ممکن است هشدار یا خطا باشند. برای مثال، ارجاعات نادرست یا کامنت‌های مفقود 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 مجاز هستند. از مقدار release متناظر با مقداری که هنگام کامپایل کد با دستور javac استفاده می‌کنید، بهره ببرید.

-sourcepath sourcepathlist

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

شما می‌توانید از گزینه -sourcepath تنها هنگام ارسال نام‌های بسته به دستور javadoc استفاده کنید. این گزینه فایل‌های مبدأ ارسال‌شده به دستور javadoc را پیدا نخواهد کرد. برای یافتن فایل‌های مبدأ، به آن دایرکتوری بروید یا مسیر را پیش از هر فایل قرار دهید، همان‌طور که در بخش Document One or More Classes نشان داده شده است. اگر -sourcepath را حذف کنید، دستور javadoc از class path برای یافتن فایل‌های مبدأ استفاده می‌کند (گزینه -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) است که نیازی به داشتن فایل‌های منبع ندارد. آرگومان‌ها در تمام سیستم‌های عامل با دو‌نقطه (:) از هم جدا می‌شوند. استفاده از نویسه‌های عمومی (Wildcardها) مجاز نیست. برای تعیین محل یافتن بسته‌ها از -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 mechanism) استفاده می‌کند. گزینهٔ 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 را هنگام تولید مستندات تعیین می‌کند. آرگومان، نام محلی‌سازی است، همان‌گونه که در مستندات java.util.Locale شرح داده شده است، مانند en_US (انگلیسی، ایالات متحده) یا en_US_WIN (گونهٔ ویندوز).

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

تعیین یک محلی‌سازی باعث می‌شود دستور javadoc فایل‌های منبع (resource files) آن محلی‌سازی را برای پیام‌هایی مانند رشته‌های موجود در نوار ناوبری، سربرگ‌های فهرست‌ها و جدول‌ها، محتوای فایل‌های راهنما، توضیحات موجود در فایل stylesheet.css و غیره انتخاب کند. همچنین ترتیب مرتب‌سازی برای فهرست‌های مرتب‌شده بر اساس حروف الفبا و جداکنندهٔ جمله را برای تعیین پایان اولین جمله مشخص می‌سازد. گزینهٔ -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 استاندارد در جریان خروجی آن نمایش می‌یابد. بخش «اجرای دستور Javadoc» (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 page) برای هر کلاس و بستهٔ مستندشده ایجاد می‌کند. این صفحه مشخص می‌کند چه بسته‌ها، کلاس‌ها، متدها، سازنده‌ها و فیلدهایی از هرگونه API کلاس یا بستهٔ مشخص‌شده استفاده می‌کنند. با فرض کلاس C، مواردی که از کلاس C استفاده می‌کنند شامل زیرکلاس‌های C، فیلدهای اعلان‌شده از نوع C، متدهایی که C را برمی‌گردانند، و متدها و سازنده‌هایی با پارامترهایی از نوع C خواهند بود. برای مثال، می‌توانید به صفحهٔ Use برای نوع String نگاه کنید. از آنجا که متد getName در کلاس java.awt.Font نوع String را برمی‌گرداند، متد getName از String استفاده می‌کند و بنابراین متد getName در صفحهٔ Use مربوط به String ظاهر می‌شود. این گزینه تنها کاربردهای API را مستند می‌کند، نه پیاده‌سازی را. اگر متدی در پیاده‌سازی داخلی خود از String استفاده کند، اما رشته‌ای را به عنوان آرگومان دریافت نکند یا برنگرداند، استفاده از String در نظر گرفته نمی‌شود. برای دسترسی به صفحهٔ Use تولیدشده، به کلاس یا بسته رفته و روی پیوند Use link در نوار ناوبری کلیک کنید.

-version

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

-author

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

-splitindex

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

-windowtitle title

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

-doctitle title

عنوانی را مشخص می‌کند که در نزدیکی بالای فایل خلاصهٔ کلی (overview summary) قرار می‌گیرد. متن مشخص‌شده در برچسب 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 و فاصلهٔ خالی باشد، اما در این صورت، header باید در نشانه‌های نقل‌قول محصور شود. برای علامت‌های نقل‌قول درونی در سرآیند از نویسه‌های گریز استفاده کنید. برای مثال، javadoc -header "<b>Java Platform </b><br>v1.4" com.mypackage.

-footer footer

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

-top

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

-bottom text

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

-link extdocURL

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

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

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

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

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

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

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

•

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

•

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

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

اگر می‌خواهید به بسته‌های پلتفرم Java مانند java.lang، java.io و سایر بسته‌های نمایش‌داده‌شده در 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 را ببینید. کاربرد دیگر آن برای ایجاد پیوندهای متقابل بین مجموعه‌هایی از بسته‌ها است: دستور 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) {}

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

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

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

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

برای نمونه، فهرست بسته‌ها برای API جاوا SE در 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 را برای پیوند دادن به هر تعداد سند تولیدشده خارجی ارائه دهید. نسخه 1.2 برنامه Javadoc دارای یک باگ شناخته‌شده بود که از ارائه بیش از یک گزینه -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 را روی کل درخت کد منبع اجرا کرده‌اید، می‌توانید به سرعت تغییرات کوچکی در کامنت‌های مستندسازی ایجاد کنید و دستور javadoc را دوباره روی بخشی از درخت منبع اجرا نمایید. توجه داشته باشید که اجرای دوم تنها در صورتی به درستی کار می‌کند که تغییرات شما مربوط به کامنت‌های مستندسازی باشد و نه اعلان‌ها. اگر هر گونه اعلانی را به کد منبع اضافه، حذف یا تغییر دهید، ممکن است پیوندهای شکسته در فهرست راهنما، درخت بسته، فهرست اعضای ارث‌بری‌شده، صفحه 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

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

-charset name

مجموعه‌نویسه (character set) زبان HTML را برای این سند مشخص می‌کند. نام باید یک نام ترجیحی MIME باشد، همان‌طور که در IANA Registry تحت عنوان Character Sets در نشانی 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 (شماره‌های 4197265 و 4137321)، بخش 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 Registry تحت عنوان Character Sets در نشانی 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 name) کلاس و نام‌های ساده و بدون پیشوند فیلدها و متدها هستند. سازنده‌ها (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 را به‌صورت پررنگ خروجی می‌دهد و به دنبال آن در خط بعدی متن آرگومان تکی آن قرار می‌گیرد. مشابه هر برچسب بلوکی دیگر، متن آرگومان می‌تواند حاوی برچسب‌های درون‌خطی (inline) باشد که آن‌ها نیز تفسیر می‌شوند. خروجی مشابه برچسب‌های استاندارد تک‌آرگومانی مانند برچسب‌های @return و @author است. حذف مقدار برای taghead باعث می‌شود tagname به عنوان عنوان قرار گیرد.

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

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

a (همه جا)

o (نمای کلی - overview)

p (بسته‌ها - packages)

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 برچسبی است که می‌خواهید در خروجی متوقف (suppress) شود، از این قالب استفاده کنید: -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 برای یک برچسب استاندارد قید نشود، در موقعیت پیش‌فرض خود باقی می‌ماند.

جلوگیری از تداخل: اگر می‌خواهید فضای نام اختصاصی خود را ایجاد کنید، می‌توانید از یک قرارداد نام‌گذاری جداشده با نقطه مشابه آنچه برای بسته‌ها به کار می‌رود استفاده کنید: com.mycompany.todo. شرکت Oracle به ایجاد برچسب‌های استانداردی که نام آن‌ها حاوی نقطه نیست ادامه خواهد داد. هر برچسبی که ایجاد کنید رفتار برچسبی با همان نام را که توسط Oracle تعریف شده لغو و بازنویسی می‌کند. اگر یک برچسب یا 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
فایل کلاسی را مشخص می‌کند که تگلتی را آغاز می‌کند که برای تولید مستندات برای آن تگ استفاده می‌شود. برای مقدار class از نام کامل واجد شرایط (fully qualified name) استفاده کنید. این تگلت همچنین تعداد آرگومان‌های متنی را که تگ سفارشی دارد مشخص می‌کند. تگلت این آرگومان‌ها را دریافت کرده، آن‌ها را پردازش می‌کند و خروجی را تولید می‌نماید. برای مستندات جامع به همراه نمونه‌های تگلت، ببینید: Taglet Overview در http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/taglet/overview.html

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

-taglet com.sun.tools.doclets.ToDoTaglet

-tagletpath /home/taglets 

-tag return

-tag param

-tag todo

-tag throws

-tag see

-tagletpath tagletpathlist

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

-docfilesubdirs

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

-excludedocfilessubdir name1:name2

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

-noqualifier all | packagename1:packagename2...

نام‌های بسته‌های واجد شرایط (qualifiers) را از نام کلاس‌ها در خروجی حذف می‌کند. آرگومان گزینهٔ -noqualifier یا all است (تمام واجد‌کننده‌های بسته حذف می‌شوند) یا فهرستی جداشده با دونقطه از بسته‌ها به همراه نویسه‌های عام (wildcard) است که باید به عنوان واجد‌کننده حذف شوند. نام بسته از جاهایی که نام‌های کلاس یا رابط ظاهر می‌شوند حذف می‌شود. به 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 شوند (که در غیر این صورت در هر صفحه‌ای تفاوتی وجود خواهد داشت). برچسب زمانی شامل شماره انتشار دستور javadoc است و در حال حاضر چیزی شبیه به این نمایش داده می‌شود: <!-- Generated by javadoc (build 1.5.0_01) on Thu Apr 02 14:04:52 IST 2009 -->.

-nocomment

کل بدنهٔ کامنت‌ها، شامل توضیحات اصلی و تمام تگ‌ها را سرکوب کرده و فقط اعلان‌ها را تولید می‌کند. این گزینه به شما امکان می‌دهد از فایل‌های مبدأیی که در ابتدا برای هدف دیگری در نظر گرفته شده بودند دوباره استفاده کنید تا بتوانید در مراحل اولیهٔ یک پروژه جدید، مستندات HTML اسکلتی تولید نمایید.

-sourcetab tablength

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

مثال‌های ساده (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

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

به دایرکتوری والد بسته‌ای با نام کامل بروید. سپس دستور javadoc را همراه با نام یک یا چند بسته‌ای که قصد مستندسازی آن‌ها را دارید اجرا کنید:

cd /home/src/

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

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

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

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

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

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

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

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

نتیجه این است که در تمام موارد، مستنداتی با قالب‌بندی HTML برای کلاس‌ها و رابط‌های public و protected در بسته‌های java.awt و java.awt.event تولید شده و فایل‌های HTML در دایرکتوری مقصد مشخص‌شده ذخیره می‌شوند. از آنجا که دو یا چند بسته در حال تولید هستند، سند دارای سه فریم 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. هیچ‌یک از گزینه‌ها نباید شامل نویسه‌های خط جدید (newline) میان علامت‌های نقل‌قول تکی باشند. برای مثال، اگر این نمونه را کپی و جای‌گذاری می‌کنید، نویسه‌های خط جدید را از گزینهٔ -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 جریان‌های ورودی، خروجی استاندارد و خطای استاندارد را تعیین می‌کنند. مقدار Null به ترتیب مقدار پیش‌فرض برای System.in، System.out و System.err است.

مثال MAKEFILE (THE MAKEFILE EXAMPLE)

این یک نمونه از یک makefile در GNU است. علامت‌های نقل‌قول تکی آرگومان‌های makefile را احاطه می‌کنند. برای یک نمونه از makefile در Windows، بخش makefiles از پرسش‌های متداول Javadoc را در آدرس 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 متن سربرگ (header) را در پاورقی کپی می‌کند.

•

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