javadoc(1) Basic Tools javadoc(1)
نام (NAME)
javadoc - تولید صفحات HTML مستندات API از فایلهای منبع Java.
خلاصه دستور (SYNOPSIS)
javadoc {packages|source-files} [options] [@argfiles]
packages
نام بسته‌هایی که می‌خواهید مستندسازی کنید، جدا شده با فاصله، برای
نمونه java.lang java.lang.reflect java.awt. اگر می‌خواهید
زیربسته‌ها را نیز مستندسازی کنید، از گزینهٔ -subpackages برای
تعیین بسته‌ها استفاده کنید.
به‌طور پیش‌فرض، javadoc بسته‌های مشخص‌شده را در دایرکتوری جاری و
زیردایرکتوری‌های آن جستجو می‌کند. از گزینهٔ -sourcepath برای تعیین
فهرست دایرکتوری‌هایی که بسته‌ها در آنها جستجو شوند استفاده نمایید.
source-files
نام فایلهای منبع Java که می‌خواهید مستندسازی کنید، جدا شده با
فاصله، برای نمونه Class.java Object.java Button.java. به‌طور
پیش‌فرض، javadoc کلاس‌های مشخص‌شده را در دایرکتوری جاری جستجو
می‌کند. با این حال، می‌توانید مسیر کامل به فایل کلاس را مشخص کرده
و از نویسه‌های عام (wildcard) استفاده کنید، برای نمونه
/home/src/java/awt/Graphics*.java. همچنین می‌توانید مسیر را
به‌صورت نسبی نسبت به دایرکتوری جاری تعیین نمایید.
options
گزینه‌های خط فرمان، جدا شده با فاصله. بخش گزینه‌ها (Options) را
ببینید.
@argfiles
نام فایلهایی که فهرستی از گزینه‌های دستور javadoc، نام بسته‌ها و
نام فایلهای منبع را به هر ترتیبی در بر دارند.
توضیحات (DESCRIPTION)
دستور javadoc اعلان‌ها و کامنت‌های مستندسازی را در مجموعه‌ای از فایلهای
منبع Java تجزیه کرده و مجموعه‌ای متناظر از صفحات HTML تولید می‌کند که
(به‌طور پیش‌فرض) کلاس‌های public و protected، کلاس‌های تودرتو (اما نه
کلاس‌های داخلی ناشناس)، رابط‌ها (interfaces)، سازنده‌ها (constructors)،
متدها (methods) و فیلدها (fields) را توصیف می‌کنند. می‌توانید از دستور
javadoc برای تولید مستندات API یا مستندات پیاده‌سازی برای مجموعه‌ای از
فایلهای منبع استفاده کنید.
می‌توانید دستور javadoc را روی بسته‌های کامل، فایلهای منبع منفرد، یا هر
دو اجرا کنید. هنگام مستندسازی بسته‌های کامل، می‌توانید یا از گزینهٔ
-subpackages برای پیمایش بازگشتی یک دایرکتوری و زیردایرکتوری‌های آن
استفاده کنید، یا فهرستی صریح از نام‌های بسته را ارسال نمایید. هنگامی که
فایلهای منبع منفرد را مستندسازی می‌کنید، فهرستی از نام‌های فایلهای منبع
Java را ارسال کنید. بخش مثال‌های ساده (Simple Examples) را ببینید.
پردازش فایلهای منبع (PROCESS SOURCE FILES)
دستور javadoc فایلهایی را که پسوند منبع دارند و سایر فایلهای شرح
داده‌شده در بخش فایلهای منبع (Source Files) پردازش می‌کند. اگر دستور
javadoc را با ارسال نام‌های منفرد فایلهای منبع اجرا کنید، می‌توانید دقیقاً
تعیین کنید که کدام فایلهای منبع پردازش شوند. با این حال، بیشتر
توسعه‌دهندگان بدین صورت کار نمی‌کنند، زیرا ارسال نام بسته‌ها ساده‌تر است.
دستور javadoc می‌تواند بدون تعیین صریح نام فایلهای منبع به سه روش اجرا
شود: می‌توانید نام بسته‌ها را ارسال کنید، از گزینهٔ -subpackages استفاده
نمایید، یا از نویسه‌های عام (wildcards) همراه با نام فایلهای منبع بهره
ببرید. در این موارد، دستور javadoc تنها در صورتی یک فایل منبع را پردازش
می‌کند که فایل تمام شرایط زیر را برآورده سازد:
• پیشوند نام فایل (با حذف .java) یک نام کلاس معتبر باشد.
• نام مسیر نسبت به ریشهٔ درخت منبع، پس از تبدیل جداکننده‌ها به نقطه، یک
نام بستهٔ معتبر باشد.
• عبارت package حاوی نام بستهٔ معتبر باشد.
پردازش پیوندها (Processing Links)
در حین یک اجرا، دستور javadoc پیوندهای ارجاع‌متقاطع (cross-reference) را
به نام‌های بسته، کلاس و عضوی که بخشی از آن اجرا هستند اضافه می‌کند.
پیوندها در مکان‌های زیر ظاهر می‌شوند. برای شرح برچسب‌های @، بخش برچسب‌های
Javadoc (Javadoc Tags) را ببینید.
• اعلان‌ها (انواع بازگشتی، انواع آرگومان‌ها، و انواع فیلدها).
• بخش‌های همچنین ببینید (See Also) که از برچسب‌های @see تولید شده‌اند.
• متن درون‌خطی تولید شده از برچسب‌های {@link}.
• نام استثناها که از برچسب‌های @throws تولید شده‌اند.
• پیوندهای Specified by به اعضای رابط و پیوندهای Overrides به اعضای
کلاس. بخش Method Comment Inheritance را ببینید.
• جدول‌های خلاصه‌ای که بسته‌ها، کلاس‌ها و اعضا را فهرست می‌کنند.
• درخت‌های وراثت بسته و کلاس.
• نمایه (index).
می‌توانید با استفاده از گزینه‌های -link و -linkoffline، پیوندهایی را به
متن‌های موجود برای کلاس‌هایی که در خط فرمان گنجانده نشده‌اند (اما به‌طور
جداگانه تولید شده‌اند) بیفزایید.
جزئیات پردازش (Processing Details)
دستور javadoc در هر بار اجرا یک سند کامل ایجاد می‌کند. این دستور ساخت
افزایشی (incremental build) انجام نمی‌دهد که نتایج اجراهای پیشین را
ویرایش کرده یا مستقیماً ادغام کند. با این حال، دستور javadoc می‌تواند به
نتایج حاصل از سایر اجراها پیوند دهد.
پیاده‌سازی دستور javadoc به کامپایلر Java نیاز داشته و بر آن متکی است.
دستور javadoc بخشی از دستور javac را فرامی‌خواند تا اعلان‌ها را کامپایل
کرده و از پیاده‌سازی اعضا چشم‌پوشی کند. دستور javadoc یک بازنمایی درونی
غنی از کلاس‌ها شامل سلسله‌مراتب کلاس‌ها و روابط استفاده می‌سازد تا HTML را
تولید نماید. دستور javadoc همچنین مستندات ارائه‌شده توسط کاربر را از
کامنت‌های مستندسازی در کد منبع استخراج می‌کند. بخش کامنت‌های مستندسازی
(Documentation Comments) را ببینید.
دستور javadoc روی فایلهای منبعی که فایلهای ساختگیِ صرف (stub files) بدون
بدنهٔ متد هستند نیز اجرا می‌شود. این بدان معناست که می‌توانید در مراحل
اولیهٔ طراحی پیش از پیاده‌سازی API، کامنت‌های مستندسازی بنویسید و دستور
javadoc را اجرا کنید.
اتکا به کامپایلر اطمینان می‌دهد که خروجی HTML دقیقاً با پیاده‌سازی واقعی
مطابقت داشته باشد؛ پیاده‌سازی‌ای که ممکن است به‌جای کد منبع صریح، بر کدهای
ضمنی متکی باشد. برای نمونه، دستور javadoc سازنده‌های پیش‌فرضی را که در
فایلهای کلاس کامپایل‌شده موجودند ولی در کد منبع وجود ندارند، مستندسازی
می‌کند.
در بسیاری از موارد، دستور javadoc به شما اجازه می‌دهد تا برای فایلهای
منبع با کدهای ناقص یا دارای خطا نیز مستندات تولید کنید. می‌توانید پیش از
اتمام تمام اشکال‌زدایی‌ها و عیب‌یابی‌ها، مستندات را ایجاد نمایید. دستور
javadoc بررسی‌های اولیه‌ای روی کامنت‌های مستندسازی انجام می‌دهد.
هنگامی که دستور javadoc ساختار درونی خود را برای مستندسازی می‌سازد، تمام
کلاس‌های ارجاع‌داده‌شده را بارگذاری می‌کند. به همین دلیل، دستور javadoc
باید بتواند همهٔ کلاس‌های ارجاع‌شده را، اعم از کلاس‌های راه‌انداز (bootstrap
classes)، افزونه‌ها (extensions)، یا کلاس‌های کاربر بیابد. به بخش How
Classes Are Found در آدرس
http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html
مراجعه کنید.
به‌طور معمول، کلاس‌هایی که ایجاد می‌کنید باید یا به‌عنوان یک افزونه
بارگذاری شوند یا در مسیر کلاس (class path) دستور javadoc قرار گیرند..SS
"داکلت‌های JAVADOC (JAVADOC DOCLETS)" شما می‌توانید محتوا و قالب خروجی
دستور javadoc را با داکلت‌ها سفارشی‌سازی کنید. دستور javadoc دارای یک
داکلت درونی پیش‌فرض به نام داکلت استاندارد (standard doclet) است که
مستندات API با قالب HTML تولید می‌کند. شما می‌توانید داکلت استاندارد را
تغییر دهید، از آن زیرکلاس بسازید، یا داکلت اختصاصی خود را بنویسید تا
خروجی‌هایی در قالب‌های HTML، XML، MIF، RTF یا هر قالب دلخواه دیگری تولید
کند.
هنگامی که یک داکلت سفارشی با گزینه -doclet تعیین نشده باشد، دستور
javadoc از داکلت استاندارد پیش‌فرض استفاده می‌کند. دستور javadoc دارای
گزینه‌های متعددی است که صرف‌نظر از داکلتِ در حال استفاده، در دسترس هستند.
داکلت استاندارد مجموعه‌ای تکمیلی از گزینه‌های خط فرمان را ارائه می‌دهد.
بخش گزینه‌ها (Options) را ببینید.
فایلهای منبع (SOURCE FILES)
دستور javadoc خروجی‌هایی تولید می‌کند که از انواع فایلهای منبع زیر سرچشمه
می‌گیرند: فایلهای منبع زبان جاوا برای کلاس‌ها (.java)، فایلهای توضیحات
بسته، فایلهای توضیحات کلی (overview)، و فایلهای پردازشنشده گوناگون. این
بخش همچنین فایلهای آزمون و فایلهای الگو را شرح می‌دهد که ممکن است در
درخت منبع وجود داشته باشند، اما می‌خواهید مطمئن شوید که مستندسازی
نمی‌شوند.
فایلهای منبع کلاس (CLASS SOURCE FILES)
هر کلاس یا رابط (interface) و اعضای آن می‌توانند توضیحات مستندسازی مربوط
به خود را در یک فایل منبع داشته باشند. بخش Documentation Comments را
ببینید.
فایلهای توضیحات بسته (PACKAGE COMMENT FILES)
هر بسته می‌تواند توضیحات مستندسازی مربوط به خود را در فایل منبع
اختصاصی‌اش داشته باشد که دستور javadoc آن را در صفحه خلاصه بسته (package
summary) ادغام می‌کند. شما معمولاً هر مستنداتی را که برای کل بسته اعمال
می‌شود در این توضیحات قرار می‌دهید.
برای ایجاد یک فایل توضیحات بسته، می‌توانید توضیحات خود را در یکی از
فایلهای زیر قرار دهید:
• فایل package-info.java می‌تواند شامل اعلان بسته، حاشیه‌نویسی‌های بسته
(package annotations)، توضیحات بسته و برچسب‌های Javadoc باشد. استفاده
از این فایل ترجیح داده می‌شود.
• فایل package.html تنها شامل توضیحات بسته و برچسب‌های Javadoc است و
حاشیه‌نویسی‌های بسته را نمی‌پذیرد.
یک بسته می‌تواند یک فایل package.html تکی یا یک فایل package-info.java
تکی داشته باشد، اما نباید شامل هر دوی آنها باشد. هر یک از این فایلها را
در دایرکتوری بسته در درخت منبع و در کنار فایلهای منبع خود قرار دهید.
فایل package-info.java
فایل package-info.java می‌تواند شامل توضیح بسته‌ای با ساختار زیر باشد.
این توضیح پیش از اعلان بسته قرار می‌گیرد.
نکته: جداکننده‌های توضیح /** و */ باید وجود داشته باشند، اما می‌توان از
ستاره‌های ابتدای خطوط میانی صرف‌نظر کرد.
/**
* Provides the classes necessary to create an
* applet and the classes an applet uses
* to communicate with its applet context.
*
* 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 می‌تواند شامل توضیح بسته‌ای با ساختار زیر باشد. این
توضیح در عنصر
قرار می‌گیرد.
فایل: java/applet/package.html
Provides the classes necessary to create an applet and the
classes an applet uses to communicate with its applet context.
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.html یک فایل استاندارد HTML است و شامل اعلان بسته نمی‌شود.
محتوای این فایل توضیحات، به استثنای یک مورد، به زبان HTML نوشته می‌شود.
در توضیحات مستندسازی نباید از جداکننده‌های توضیح /** و */ یا ستاره‌های
ابتدای خط استفاده شود. هنگام نوشتن این توضیحات، نخستین جمله را خلاصه‌ای
درباره بسته قرار دهید و از گذاشتن عنوان یا هر متن دیگری میان تگ
و نخستین جمله خودداری کنید. می‌توانید برچسب‌های بسته را درج کنید. تمام
برچسب‌های بلوکی (block tags) باید پس از توضیحات اصلی قرار گیرند. اگر یک
برچسب @see در فایل توضیحات بسته اضافه می‌کنید، باید نام کاملاً مشخص
(fully qualified name) داشته باشد.
پردازش فایل توضیحات
هنگامی که دستور javadoc اجرا می‌شود، به دنبال فایل توضیحات بسته می‌گردد.
در صورت یافتن فایل توضیحات بسته، دستور javadoc مراحل زیر را انجام
می‌دهد:
• توضیحات را جهت پردازش کپی می‌کند. برای package.html، دستور javadoc
تمام محتوای میان تگ‌های HTML و را کپی می‌کند. می‌توانید
بخش را برای درج تگ ، بیانیه حق نشر فایل منبع، یا
اطلاعات دیگر اضافه کنید؛ با این حال، هیچ‌کدام از این موارد در مستندات
تولیدشده نمایش داده نخواهند شد.
• برچسب‌های بسته را پردازش می‌کند. بخش Package Tags را ببینید.
• متن پردازش‌شده را در پایین صفحه خلاصه بسته درج می‌کند. بخش Java
Platform, Standard Edition API Specification Overview را در
http://docs.oracle.com/javase/8/docs/api/overview-summary.html
ببینید.
• نخستین جمله توضیحات بسته را به بالای صفحه خلاصه بسته کپی می‌کند. دستور
javadoc همچنین نام بسته و این نخستین جمله را به فهرست بسته‌ها در صفحه
نمای کلی (overview) اضافه می‌کند. بخش Java Platform, Standard Edition
API Specification Overview را در
http://docs.oracle.com/javase/8/docs/api/overview-summary.html
ببینید.
پایان جمله بر اساس همان قواعدی تعیین می‌شود که برای تشخیص پایان جمله
نخست توضیحات اصلی کلاس و عضو به کار می‌روند..SS "فایلهای توضیحات مرور
کلی (OVERVIEW COMMENT FILES)" هر برنامه یا مجموعه‌ای از بسته‌ها که
مستندسازی می‌کنید می‌تواند کامنت توضیحات مرور کلی (overview) مختص به
خود را داشته باشد که در فایل مبدأ جداگانه‌ای نگهداری می‌شود و دستور
javadoc آن را در صفحهٔ مرور کلیِ تولیدشده ادغام می‌کند. معمولاً در این
کامنت هرگونه مستنداتی را قرار می‌دهید که برای کل برنامه یا مجموعهٔ
بسته‌ها اعمال می‌شود.
می‌توانید هر نامی که می‌خواهید، مانند overview.html، برای این فایل انتخاب
کرده و آن را در هر جایی قرار دهید. یک مکان متداول در بالاترین سطح درخت
سورس است.
به‌عنوان مثال، اگر فایلهای سورس بستهٔ java.applet در دایرکتوری
/home/user/src/java/applet قرار داشته باشند، می‌توانید یک فایل کامنت
مرور کلی در /home/user/src/overview.html بسازید.
می‌توانید برای همان مجموعه فایلهای سورس، چندین فایل کامنت مرور کلی داشته
باشید، در صورتی که بخواهید دستور javadoc را چندین بار بر روی مجموعه‌های
متفاوتی از بسته‌ها اجرا کنید. برای مثال، می‌توانید دستور javadoc را یک
بار با گزینهٔ -private برای مستندات داخلی و بار دیگر بدون این گزینه برای
مستندات عمومی اجرا کنید. در این حالت، می‌توانید در جملهٔ نخست هر فایل
کامنت مرور کلی، مستندات را به‌صورت عمومی یا داخلی توصیف کنید.
محتوای فایل کامنت مرور کلی، یک کامنت مستندات بزرگ است که با HTML نوشته
شده است. جملهٔ نخست را خلاصه‌ای دربارهٔ برنامه یا مجموعهٔ بسته‌ها قرار دهید.
بین تگ <body> و جملهٔ نخست، هیچ عنوان یا متن دیگری قرار ندهید. تمام تگ‌ها
به‌جز تگ‌های درون‌خطی، مانند تگ {@link}، باید پس از توضیحات اصلی بیایند.
اگر یک تگ @see اضافه می‌کنید، باید دارای یک نام کاملاً مشخص (fully
qualified name) باشد.
هنگام اجرای دستور javadoc، نام فایل کامنت مرور کلی را با گزینهٔ
-overview مشخص کنید. سپس فایل به‌شیوه‌ای مشابه با فایل کامنت بسته پردازش
می‌شود. دستور javadoc کارهای زیر را انجام می‌دهد:
• تمامی محتوای بین تگ‌های <body> و </body> را برای پردازش کپی می‌کند.
• تگ‌های مرور کلی موجود را پردازش می‌کند. بخش Overview Tags را ببینید.
• متن پردازش‌شده را در انتهای صفحهٔ مرور کلیِ تولیدشده درج می‌کند. بخش Java
Platform Standard Edition API Specification Overview را در
http://docs.oracle.com/javase/8/docs/api/overview-summary.html ببینید
• جملهٔ نخست کامنت مرور کلی را در بالای صفحهٔ خلاصه مرور کلی کپی می‌کند.
فایلهای پردازشنشده (UNPROCESSED FILES)
فایلهای سورس شما می‌توانند شامل هر فایلی باشند که می‌خواهید دستور javadoc
آنها را در دایرکتوری مقصد کپی کند. این فایلها معمولاً شامل فایلهای
گرافیکی، فایلهای سورس و class نمونهٔ جاوا، و فایلهای HTML مستقلی هستند
که محتوای زیاد آنها ممکن است کامنت مستندات یک فایل سورس جاوای معمولی را
بیش از حد شلوغ کند.
برای گنجاندن فایلهای پردازشنشده، آنها را در دایرکتوری‌ای به نام doc-
files قرار دهید. دایرکتوری doc-files می‌تواند یک زیردایرکتوری از هر
دایرکتوری بسته‌ای باشد که شامل فایلهای سورس است. شما می‌توانید برای هر
بسته یک زیردایرکتوری doc-files داشته باشید.
برای مثال، اگر می‌خواهید تصویر یک دکمه را در مستندات کلاس
java.awt.Button بگنجانید، فایل تصویر را در دایرکتوری
/home/user/src/java/awt/doc-files/ قرار دهید. دایرکتوری doc-files را در
/home/user/src/java/doc-files قرار ندهید، زیرا java یک بسته نیست و هیچ
فایل سورسی در بر ندارد.
تمام پیوندها به فایلهای پردازشنشده باید در کد گنجانده شوند زیرا دستور
javadoc به این فایلها نگاه نمی‌کند. دستور javadoc این دایرکتوری و تمام
محتویات آن را در مقصد کپی می‌کند. مثال زیر نشان می‌دهد که پیوند در کامنت
مستندات Button.java چگونه ممکن است باشد:
/**
* This button looks like this:
* <img src="doc-files/Button.gif">
*/
فایلهای آزمون و الگو (TEST AND TEMPLATE FILES)
می‌توانید فایلهای آزمون و الگو را در درخت سورس، در همان دایرکتوری یا در
زیردایرکتوری‌ای از دایرکتوری قرارگیری فایلهای سورس ذخیره کنید. برای
جلوگیری از پردازش فایلهای آزمون و الگو، دستور javadoc را اجرا کرده و
نام‌های تک‌تک فایلهای سورس را صراحتاً به آن ارسال کنید.
فایلهای آزمون، فایلهای سورس معتبر و قابل کامپایل هستند. فایلهای الگو
فایلهای سورس معتبر و سازگار نیستند، اما اغلب پسوند .java دارند.
فایلهای آزمون (Test Files)
اگر می‌خواهید فایلهای آزمون شما به یک بستهٔ بدون نام یا به بسته‌ای غیر از
بستهٔ فایلهای سورس تعلق داشته باشند، فایلهای آزمون را در یک زیردایرکتوری
در زیر فایلهای سورس قرار دهید و یک نام نامعتبر به آن دایرکتوری اختصاص
دهید. اگر فایلهای آزمون را در همان دایرکتوریِ سورس قرار دهید و دستور
javadoc را با یک آرگومان خط فرمان که نشان‌دهندهٔ نام بسته است فراخوانی
کنید، فایلهای آزمون موجب هشدار یا خطا می‌شوند. اگر فایلها در
زیردایرکتوری با نام نامعتبر باشند، دایرکتوری فایلهای آزمون نادیده گرفته
شده و هیچ خطا یا هشداری صادر نمی‌شود. برای مثال، برای افزودن فایلهای
آزمون برای فایلهای سورس در com.package1، آنها را در زیردایرکتوری‌ای با
یک نام بستهٔ نامعتبر قرار دهید. نام دایرکتوری زیر نامعتبر است زیرا حاوی
خط پیوند (hyphen) می‌باشد:
com/package1/test-files/
اگر فایلهای آزمون شما حاوی کامنت‌های مستندات هستند، می‌توانید یک اجرای
جداگانه از دستور javadoc را با ارسال نام‌های فایلهای سورس آزمون با
استفاده از نویسه‌های عمومی (wildcards)، مانند com/package1/test-
files/*.java، برای تولید مستندات فایلهای آزمون برپا کنید.
فایلهای الگو (Template Files)
اگر می‌خواهید یک فایل الگو در دایرکتوری سورس باشد، اما هنگام اجرای دستور
javadoc خطایی تولید نکند، یک نام فایل نامعتبر مانند Buffer-
Template.java به آن بدهید تا از پردازش آن جلوگیری شود. دستور javadoc
تنها فایلهای سورسی را پردازش می‌کند که نام آنها پس از حذف پسوند .java،
یک نام کلاس معتبر باشد.
فایلهای تولیدشده (GENERATED FILES)
به‌طور پیش‌فرض، دستور javadoc از یک doclet استاندارد استفاده می‌کند که
مستنداتی با قالب‌بندی HTML تولید می‌کند. این doclet استاندارد، صفحه‌های
محتوای اصلی، ارجاع متقابل، و صفحه‌های پشتیبانی شرح داده‌شده در اینجا را
تولید می‌کند. هر صفحهٔ HTML با یک فایل جداگانه متناظر است. دستور javadoc
دو نوع فایل تولید می‌کند. نوع اول بر اساس کلاس‌ها و رابط‌ها نام‌گذاری
می‌شود. نوع دوم حاوی خط پیوند است (مانند package-summary.html) تا از
تداخل با نوع اول فایلها جلوگیری شود.
صفحه‌های محتوای اصلی (BASIC CONTENT PAGES)
• یک صفحهٔ کلاس یا رابط (classname.html) برای هر کلاس یا رابطی که
مستندسازی می‌شود.
• یک صفحهٔ بسته (package-summary.html) برای هر بسته‌ای که مستندسازی
می‌شود. دستور javadoc هر متن HTML ارائه‌شده در فایلی به نام
package.html یا package-info.java در دایرکتوری بسته در درخت سورس را
در بر می‌گیرد.
• یک صفحهٔ مرور کلی (overview-summary.html) برای کل مجموعهٔ بسته‌ها. صفحهٔ
مرور کلی صفحهٔ نخست مستندات تولیدشده است. دستور javadoc هر متن HTML
ارائه‌شده در فایلی را که توسط گزینهٔ -overview مشخص شده در بر می‌گیرد.
صفحهٔ Overview تنها زمانی ایجاد می‌شود که دو یا چند نام بسته را به
دستور javadoc بدهید. بخش‌های HTML Frames و گزینه‌ها (Options) را
ببینید.
صفحه‌های ارجاع متقابل (CROSS-REFERENCE PAGES)
• یک صفحهٔ سلسله‌مراتب کلاس برای کل مجموعهٔ بسته‌ها (overview-tree.html).
برای مشاهدهٔ صفحهٔ سلسله‌مراتب، روی Overview در نوار ناوبری و سپس روی
Tree کلیک کنید.
• یک صفحهٔ سلسله‌مراتب کلاس برای هر بسته (package-tree.html). برای مشاهدهٔ
صفحهٔ سلسله‌مراتب، به صفحهٔ یک بسته، کلاس یا رابط خاص بروید و برای نمایش
سلسله‌مراتب آن بسته، روی Tree کلیک کنید.
• یک صفحهٔ استفاده برای هر بسته (package-use.html) و یک صفحهٔ استفادهٔ
مجزا برای هر کلاس و رابط (class-use/classname.html). صفحهٔ استفاده شرح
می‌دهد که چه بسته‌ها، کلاس‌ها، متدها، سازنده‌ها و فیلدهایی از هر بخش از
کلاس، رابط یا بستهٔ مشخص‌شده استفاده می‌کنند. برای مثال، با فرض یک کلاس
یا رابط A، صفحهٔ استفادهٔ آن شامل زیرکلاس‌های A، فیلدهای اعلان‌شده به‌صورت
A، متدهایی که A برمی‌گردانند، و متدها و سازندگانی با پارامترهایی از
نوع A است. برای مشاهدهٔ صفحهٔ استفاده، به بسته، کلاس یا رابط رفته و روی
پیوند Use در نوار ناوبری کلیک کنید.
• یک صفحهٔ API منسوخ‌شده (deprecated-list.html) که تمام APIهای منسوخ‌شده و
جایگزین‌های پیشنهادی آنها را فهرست می‌کند. از APIهای منسوخ‌شده اجتناب
کنید زیرا ممکن است در پیاده‌سازی‌های آینده حذف شوند.
• یک صفحهٔ مقادیر فیلدهای ثابت (constant-values.html) برای مقادیر
فیلدهای استاتیک.
• یک صفحهٔ فرم سریال‌سازی‌شده (serialized-form.html) که اطلاعاتی دربارهٔ
کلاس‌های قابل سریال‌سازی و قابل برون‌ریزی به همراه شرح فیلدها و متدها
ارائه می‌دهد. اطلاعات این صفحه برای پیاده‌سازان مجدد کاربرد دارد و نه
برای توسعه‌دهندگانی که می‌خواهند از API استفاده کنند. برای دسترسی به
صفحهٔ فرم سریال‌سازی‌شده، به هر کلاس سریال‌سازی‌شده بروید و در بخش See
Also کامنت کلاس، روی Serialized Form کلیک کنید. doclet استاندارد یک
صفحهٔ فرم سریال‌سازی‌شده تولید می‌کند که هر کلاسی (عمومی یا غیرعمومی) را
که Serializable را به همراه متدهای readObject و writeObject آن،
فیلدهایی که سریال‌سازی می‌شوند، و کامنت‌های مستندات ناشی از تگ‌های
@serial، @serialField، و @serialData پیاده‌سازی کرده است فهرست می‌کند.
کلاس‌های سریال‌پذیر عمومی را می‌توان با علامت‌گذاری آنها (یا بستهٔ آنها)
با @serial exclude مستثنی کرد، و کلاس‌های سریال‌پذیر با سطح دسترسی بسته
را می‌توان با علامت‌گذاری آنها (یا بستهٔ آنها) با یک @serial include
گنجاند. از نگارش 1.4 به بعد، می‌توانید فرم کامل سریال‌سازی‌شده را برای
کلاس‌های عمومی و خصوصی با اجرای دستور javadoc بدون مشخص کردن گزینهٔ
-private تولید کنید. بخش گزینه‌ها (Options) را ببینید.
• یک صفحهٔ نمایه (index-*.html) از تمام نام‌های کلاس‌ها، رابط‌ها، سازنده‌ها،
فیلدها و متدها، به ترتیب حروف الفبا. صفحهٔ نمایه برای یونیکد
بین‌المللی‌سازی شده است و می‌تواند به‌عنوان یک فایل واحد یا به‌عنوان یک
فایل جداگانه برای هر نویسهٔ آغازین (مانند A–Z برای انگلیسی) تولید شود.
صفحه‌های پشتیبانی (SUPPORT PAGES)
• یک صفحهٔ راهنما (help-doc.html) که نوار ناوبری و صفحه‌های قبلی را شرح
می‌دهد. از -helpfile برای بازنویسی فایل راهنمای پیش‌فرض با فایل راهنمای
سفارشی خود استفاده کنید.
• یک فایل index.html که فریم‌های HTML را برای نمایش ایجاد می‌کند. این
فایل را برای نمایش صفحهٔ نخست همراه با فریم‌ها بارگذاری کنید. فایل
index.html هیچ محتوای متنی ندارد.
• چندین فایل فریم (*-frame.html) که حاوی فهرست‌هایی از بسته‌ها، کلاس‌ها و
رابط‌ها هستند. فایلهای فریم، فریم‌های HTML را نمایش می‌دهند.
• یک فایل فهرست بسته (package-list) که توسط گزینه‌های -link و
-linkoffline استفاده می‌شود. فایل فهرست بسته یک فایل متنی است که از
طریق پیوندها قابل دسترسی نیست.
• یک فایل برگه‌سبک (stylesheet.css) که مقدار محدودی از رنگ، خانوادهٔ قلم،
اندازهٔ قلم، سبک قلم و اطلاعات جای‌گیری در صفحه‌های تولیدشده را کنترل
می‌کند.
• یک دایرکتوری doc-files که فایلهای تصویری، نمونه، کد منبع یا دیگر
فایلهایی را که می‌خواهید در دایرکتوری مقصد کپی شوند نگهداری می‌کند. این
فایلها توسط دستور javadoc پردازش نمی‌شوند. این دایرکتوری پردازش نمی‌شود
مگر اینکه در درخت سورس وجود داشته باشد.
بخش گزینه‌ها (Options) را ببینید..SS "فریم‌های HTML (HTML FRAMES)" دستور
javadoc بر اساس مقادیر ارائه‌شده به آن، حداقل تعداد فریم‌های ضروری (دو یا
سه) را تولید می‌کند. هنگامی که تنها یک نام بسته یا فایلهای منبع متعلق به
یک بسته واحد را به عنوان آرگومان به دستور javadoc می‌دهید، این دستور از
فهرست بسته‌ها صرف‌نظر می‌کند. در عوض، دستور javadoc یک فریم در ستون سمت چپ
ایجاد می‌کند که فهرست کلاس‌ها را نمایش می‌دهد. هنگامی که دو یا چند نام
بسته را ارسال می‌کنید، دستور javadoc فریم سومی ایجاد می‌کند که همه بسته‌ها
و یک صفحه مرور کلی (overview-summary.html) را فهرست می‌کند. برای گذر از
فریم‌ها، روی پیوند No Frames کلیک کنید یا از صفحه overview-summary.html
وارد مجموعه صفحات شوید.
ساختار فایلهای تولیدشده (GENERATED FILE STRUCTURE)
فایلهای کلاس و رابط (interface) تولیدشده در همان سلسله‌مراتب پوشه‌ای
سازمان‌دهی می‌شوند که فایلهای منبع و فایلهای کلاس جاوا سازمان‌دهی شده‌اند.
این ساختار شامل یک پوشه به ازای هر زیربسته (subpackage) است.
برای نمونه، سند تولیدشده برای کلاس java.applet.Applet در مسیر
java/applet/Applet.html قرار خواهد گرفت.
ساختار فایل برای بسته java.applet با فرض اینکه نام پوشه مقصد apidocs
باشد، در ادامه آمده است. تمام فایلهایی که شامل واژه frame هستند،
همان‌طور که اشاره شده در فریم‌های بالا-چپ یا پایین-چپ ظاهر می‌شوند. تمام
فایلهای HTML دیگر در فریم سمت راست نمایش داده می‌شوند.
پوشه‌ها پررنگ (bold) هستند. علامت‌های ستاره (*) نشان‌دهنده فایلها و
پوشه‌هایی است که اگر آرگومان‌های ارائه‌شده به دستور javadoc به جای نام
بسته‌ها، نام فایلهای منبع باشند، حذف می‌شوند. هنگامی که آرگومان‌ها نام
فایلهای منبع باشند، یک فهرست بسته خالی ایجاد می‌شود. پوشه doc-files در
مقصد ایجاد نمی‌شود مگر اینکه در درخت منبع وجود داشته باشد. به بخش
Generated Files مراجعه کنید.
• apidocs: پوشه سطح بالا
• index.html: صفحه اولیه که فریم‌های HTML را برپا می‌کند
• *overview-summary.html: فهرست بسته‌ها به همراه خلاصه‌ها
• overview-tree.html: سلسله‌مراتب کلاس‌ها برای همه بسته‌ها
• deprecated-list.html: رابط‌های برنامه‌نویسی (API) منسوخ‌شده برای همه
بسته‌ها
• constant-values.html: مقادیر فیلدهای ایستا (static) برای همه بسته‌ها
• serialized-form.html: فرم‌های سریال‌سازی‌شده برای همه بسته‌ها
• *overview-frame.html: همه بسته‌ها برای نمایش در فریم بالا-چپ
• allclasses-frame.html: همه کلاس‌ها برای نمایش در فریم پایین-چپ
• help-doc.html: راهنما درباره سازمان‌دهی صفحات Javadoc
• index-all.html: نمایه پیش‌فرض ایجادشده بدون گزینه -splitindex
• index-files: پوشه ایجادشده با گزینه -splitindex
• index-<number>.html: فایلهای نمایه ایجادشده با گزینه -splitindex
• package-list: نام بسته‌ها برای تفکیک ارجاع‌های خارجی
• stylesheet.css: قلم‌ها، رنگ‌ها، موقعیت‌ها و موارد دیگر را تعریف می‌کند
• java: پوشه بسته
• applet: پوشه زیربسته
• Applet.html: صفحه کلاس Applet
• AppletContext.html: رابط AppletContext
• AppletStub.html: رابط AppletStub
• AudioClip.html: رابط AudioClip
• package-summary.html: کلاس‌ها به همراه خلاصه‌ها
• package-frame.html: کلاس‌های بسته برای نمایش در فریم پایین-چپ
• package-tree.html: سلسله‌مراتب کلاس‌ها برای این بسته
• package-use.html: محل‌های استفاده از این بسته
• doc-files: پوشه فایلهای تصویر و مثال
• class-use: محل فایلهای تصویر و مثال
- Applet.html: موارد استفاده از کلاس Applet
- AppletContext.html: موارد استفاده از رابط AppletContext
- AppletStub.html: موارد استفاده از رابط AppletStub
- AudioClip.html: موارد استفاده از رابط AudioClip
• src-html: پوشه کد منبع
• java: پوشه بسته
• applet: پوشه زیربسته
- Applet.html: کد منبع Applet
- AppletContext.html: کد منبع AppletContext
- AppletStub.html: کد منبع AppletStub
- AudioClip.html: کد منبع AudioClip
دستور javadoc در ابتدای توضیحات هر کلاس، رابط (interface)، فیلد،
سازنده (constructor) و متد، اعلانی برای آن قلمِ API تولید می‌کند. برای
نمونه، اعلان کلاس Boolean عبارت است از:
public final class Boolean
extends Object
implements Serializable
اعلان متد Boolean.valueOf چنین است:
public static Boolean valueOf(String s)
دستور javadoc می‌تواند اصلاح‌کننده‌های public، protected، private،
abstract، final، static، transient و volatile را شامل شود، اما
synchronized یا native را در بر نمی‌گیرد. اصلاح‌کننده‌های synchronized و
native جزئیات پیاده‌سازی محسوب شده و بخشی از مشخصات API به شمار
نمی‌آیند.
به‌جای تکیه بر کلیدواژه‌ی synchronized، خودِ APIها باید معناشناسی
همزمانی (concurrency semantics) خود را در توضیحات اصلی کامنت مستند
سازند. برای نمونه، یک توضیح ممکن است چنین باشد: یک شیء شمارش
(enumeration) واحد نمی‌تواند به‌طور همزمان توسط چندین رشته مورد استفاده
قرار گیرد. این مستند نباید نحوه‌ی دستیابی به این معناشناسی را شرح دهد.
به‌عنوان نمونه‌ای دیگر، در حالی که گزینه‌ی Hashtable باید thread-safe
باشد، دلیلی وجود ندارد تصریح شود که این امر با همگام‌سازی تمامی متدهای
برون‌ریزی‌شده‌ی آن حاصل شده است. بهتر است حق همگام‌سازی داخلی در سطح
bucket برای دستیابی به همزمانی بیشتر محفوظ بماند.
کامنت‌های مستندسازی (DOCUMENTATION COMMENTS)
این بخش، کامنت‌های کد منبع و وراثت کامنت‌ها را شرح می‌دهد.
کامنت‌های کد منبع (SOURCE CODE COMMENTS)
می‌توانید کامنت‌های مستندسازی را در کد منبع، پیش از اعلان‌های هر کلاس،
رابط، متد، سازنده یا فیلد قرار دهید. همچنین می‌توانید کامنت‌های مستندسازی
را برای هر بسته (package) و یک مورد دیگر را برای نمای کلی (overview)
ایجاد کنید، هرچند ساختار دستوری (syntax) آنها کمی متفاوت است. یک کامنت
مستندسازی از نویسه‌های میان /** و */ پایانی تشکیل می‌شود. ستاره‌های
ابتدایی در هر خط مجاز هستند و در بخش بعدی بیشتر شرح داده شده‌اند. متن
موجود در یک کامنت می‌تواند در چندین خط ادامه یابد.
/**
* This is the typical format of a simple documentation comment
* that spans two lines.
*/
برای صرفه‌جویی در فضا می‌توانید یک کامنت را در یک خط قرار دهید:
/** This comment takes up only one line. */
محل قرارگیری کامنت‌ها (Placement of Comments)
کامنت‌های مستندسازی تنها زمانی شناسایی می‌شوند که بلافاصله پیش از
اعلان‌های کلاس، رابط، سازنده، متد یا فیلد قرار گیرند. کامنت‌های مستندسازی
قرار داده شده در بدنه‌ی یک متد نادیده گرفته می‌شوند. دستور javadoc برای
هر عبارت اعلان، تنها یک کامنت مستندسازی را به رسمیت می‌شناسد. بخش Where
Tags Can Be Used را ببینید.
یک اشتباه رایج، قرار دادن عبارت import بین کامنت کلاس و اعلان کلاس است.
در این مکان عبارت import قرار ندهید زیرا دستور javadoc کامنت کلاس را
نادیده می‌گیرد.
/**
* This is the class comment for the class Whatever.
*/
import com.example; // MISTAKE - Important not to put import statement here
public class Whatever{ }
بخش‌های کامنت (Parts of Comments)
یک کامنت مستندسازی دارای یک بخش توضیحات اصلی است که بخش تگ‌ها پس از آن
می‌آید. توضیحات اصلی پس از جداکننده‌ی آغازین /** شروع شده و تا بخش تگ‌ها
ادامه می‌یابد. بخش تگ‌ها با نخستین تگ بلوکی (block tag) آغاز می‌شود که
توسط اولین نویسه‌ی @ که خطی را آغاز کند مشخص می‌گردد (با صرف‌نظر از
ستاره‌های ابتدایی، فاصله‌ها و جداکننده‌ی آغازین /**). داشتن کامنتی که فقط
دارای بخش تگ‌ها و فاقد توضیحات اصلی باشد ممکن است. پس از شروع بخش تگ‌ها،
توضیحات اصلی نمی‌تواند ادامه یابد. آرگومان یک تگ می‌تواند در چندین خط
گسترش یابد. تعداد تگ‌ها می‌تواند نامحدود باشد، و برخی از انواع تگ‌ها را
می‌توان تکرار کرد در حالی که برخی دیگر غیرقابل تکرار هستند. برای نمونه،
این تگ @see بخش تگ‌ها را آغاز می‌کند:
/**
* This sentence holds the main description for this documentation comment.
* @see java.lang.Object
*/
تگ‌های بلوکی و درون‌خطی (Block and inline Tags)
یک تگ، کلیدواژه‌ای ویژه درون یک کامنت مستندسازی است که توسط دستور
javadoc پردازش می‌شود. دو گونه تگ وجود دارد: تگ‌های بلوکی که به صورت تگ
@tag ظاهر می‌شوند (همچنین با عنوان تگ‌های مستقل یا standalone شناخته
می‌شوند)، و تگ‌های درون‌خطی (inline) که درون آکولادها به شکل تگ {@tag}
قرار می‌گیرند. برای اینکه یک تگ بلوکی تفسیر شود، باید در ابتدای خط
بیاید، با نادیده گرفتن ستاره‌های ابتدایی، فاصله‌ها و جداکننده (/**). این
بدان معناست که می‌توانید از نویسه‌ی @ در جاهای دیگر متن استفاده کنید و به
عنوان آغاز یک تگ تفسیر نخواهد شد. اگر می‌خواهید خطی را با نویسه‌ی @ آغاز
کنید و نمی‌خواهید به عنوان تگ تفسیر شود، از نهاد HTML با عنوان @
استفاده کنید. هر تگ بلوکی دارای متنی مرتبط است که شامل هر متنی پس از تگ
تا تگ بعدی یا انتهای کامنت مستندسازی می‌شود (بدون در بر گرفتن خود تگ
بعدی). این متن مرتبط می‌تواند در چندین خط گسترش یابد. یک تگ درون‌خطی در
هر جایی که متن مجاز باشد، مجاز بوده و تفسیر می‌شود. مثال زیر شامل تگ
بلوکی @deprecated و تگ درون‌خطی {@link} است. بخش Javadoc Tags را ببینید.
/**
* @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
*/
نوشتن کامنت‌ها در HTML (Write Comments in HTML)
متن باید در قالب HTML به همراه نهادهای HTML و برچسب‌های HTML نوشته شود.
می‌توانید از هر نسخه‌ای از HTML که مرورگرتان پشتیبانی می‌کند استفاده کنید.
داکلت (doclet) استاندارد در جاهای دیگر (خارج از کامنت‌های مستندسازی) کدی
منطبق با HTML 3.2 به همراه شیوه‌نامه‌های آبشاری (CSS) و فریم‌ها تولید
می‌کند. برای فایلهای تولیدشده، به دلیل مجموعه‌فریم‌ها (frame sets)، نسخه
HTML 4.0 ترجیح داده می‌شود.
برای نمونه، نهادها برای علامت کوچکتری (<) و علامت بزرگتری (>) باید به
صورت < و > نوشته شوند. به‌طور مشابه، علامت امپرسند (&) باید به
صورت & نوشته شود. برچسب توپر HTML یعنی <b> در مثال زیر نشان داده
شده است.
/**
* This is a <b>doc</b> comment.
* @see java.lang.Object
*/
ستاره‌های ابتدایی (Leading Asterisks)
هنگامی که دستور javadoc یک کامنت مستندسازی را تجزیه می‌کند، ستاره‌های
ابتدایی (*) در هر خط دور ریخته می‌شوند و فاصله‌ها و تب‌های پیش از این
ستاره‌های ابتدایی (*) نیز حذف می‌گردند. اگر ستاره‌ی ابتدایی را در یک خط
حذف کنید، فاصله‌ی خالی ابتدایی دیگر حذف نمی‌شود؛ در نتیجه می‌توانید نمونه
کدهای خود را مستقیماً درون یک برچسب <PRE> در کامنت مستندسازی قرار دهید
در حالی که تورفتگی آن حفظ می‌شود. فاصله‌ها توسط مرورگرها نسبت به تب‌ها به
شکلی یکدست‌تر تفسیر می‌شوند. تورفتگی نسبت به حاشیه‌ی چپ سنجیده می‌شود (نه
نسبت به جداکننده‌ی /** یا برچسب <PRE>).
جمله‌ی نخست (First Sentence)
نخستین جمله‌ی هر کامنت مستندسازی باید یک جمله‌ی خلاصه‌ساز باشد که شامل
شرحی مختصر اما کامل از موجودیت اعلان‌شده باشد. این جمله در اولین نقطه‌ای
که پس از آن یک فاصله، تب یا پایان‌دهنده‌ی خط قرار گیرد، یا در نخستین تگ
بلوکی پایان می‌یابد. دستور javadoc این جمله‌ی نخست را در خلاصه‌ی اعضا
(member summary) در بالای صفحه‌ی HTML کپی می‌کند.
اعلان‌های چندفیلدی (Multiple-Field Declarations)
پلتفرم جاوا امکان اعلان چند فیلد را در یک عبارت واحد به شما می‌دهد، اما
این عبارت تنها می‌تواند یک کامنت مستندسازی داشته باشد که برای همه‌ی
فیلدها کپی می‌شود. اگر برای هر فیلد کامنت‌های مستندسازی مجزا می‌خواهید، هر
فیلد را در یک عبارت جداگانه اعلان کنید. برای نمونه، کامنت مستندسازی زیر
اگر در قالب یک اعلان واحد نوشته شود منطقی نیست و بهتر است در قالب دو
اعلان مدیریت شود:
/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // Avoid this
دستور javadoc مستندات زیر را از کد قبلی تولید می‌کند:
public int x
فاصله‌های افقی و عمودی نقطه‌ی (x, y).
public int y
فاصله‌های افقی و عمودی نقطه‌ی (x, y)..PP استفاده از برچسب‌های سربرگ
(Header Tags)
هنگام نوشتن کامنت‌های مستندسازی برای اعضا، بهتر است از برچسب‌های سربرگ
HTML مانند <H1> و <H2> استفاده نشود، زیرا دستور javadoc یک سند
ساختاریافته کامل ایجاد می‌کند و این برچسب‌های ساختاری ممکن است با
قالب‌بندی سند تولیدشده تداخل داشته باشند. با این حال، می‌توانید از این
سربرگ‌ها در کامنت‌های کلاس و بسته (package) برای ایجاد ساختار مورد نظر
خود استفاده کنید.
وراثت کامنت متد (METHOD COMMENT INHERITANCE)
دستور javadoc اجازه وراثت کامنت متد را در کلاس‌ها و رابط‌ها (interfaces)
می‌دهد تا متن‌های جاافتاده را پر کند یا به صورت صریح کامنت‌های متد را به
ارث ببرد. سازنده‌ها (constructors)، فیلدها و کلاس‌های تو در تو (nested
classes) کامنت‌های مستندسازی را به ارث نمی‌برند.
نکته: فایل منبع متدِ به ارث برده‌شده باید در مسیری که توسط گزینه
-sourcepath مشخص شده است قرار داشته باشد تا کامنت مستندسازی آن برای کپی
کردن در دسترس باشد. نه کلاس و نه بسته آن نیازی به ارسال از طریق خط
فرمان ندارند. این رفتار برخلاف نسخه 1.3.n و نسخه‌های پیشین است که در
آنها کلاس حتماً باید یک کلاس مستندشده می‌بود.
پر کردن متن جاافتاده
هنگامی که توضیحات اصلی، یا برچسب‌های @return، @param یا @throws در کامنت
یک متد وجود نداشته باشند، دستور javadoc توضیحات اصلی یا کامنت برچسب
متناظر را از متدی که آن را بازنویسی (override) یا پیاده‌سازی (implement)
کرده است (در صورت وجود) کپی می‌کند. بخش «وراثت کامنت متد» (Method
Comment Inheritance) را ببینید.
هنگامی که برچسب @param برای یک پارامتر خاص وجود ندارد، کامنت آن پارامتر
از متد بالاتر در سلسله‌مراتب وراثت کپی می‌شود. هنگامی که برچسب @throws
برای یک استثنای خاص وجود ندارد، برچسب @throws تنها در صورتی کپی می‌شود
که آن استثنا اعلان شده باشد.
این رفتار برخلاف نسخه 1.3 و نسخه‌های پیشین است که در آنها وجود هرگونه
توضیحات اصلی یا برچسب مانع از به ارث رسیدن تمام کامنت‌ها می‌شد.
بخش «برچسب‌ها و گزینه‌های Javadoc» را ببینید.
وراثت صریح
برچسب درون‌خطی {@inheritDoc} را در توضیحات اصلی متد یا کامنت برچسب‌های
@return، @param یا @throws درج کنید. توضیحات اصلی یا کامنت برچسب به ارث
رسیده متناظر در همان مکان کپی می‌شود.
وراثت کلاس و رابط (CLASS AND INTERFACE INHERITANCE)
وراثت کامنت در تمام حالت‌های ممکنِ وراثت از کلاس‌ها و رابط‌ها رخ می‌دهد:
• هنگامی که یک متد در یک کلاس، متدی را در یک سوپرکلاس (superclass)
بازنویسی (override) می‌کند
• هنگامی که یک متد در یک رابط، متدی را در یک رابط والد (superinterface)
بازنویسی می‌کند
• هنگامی که یک متد در یک کلاس، متدی را در یک رابط پیاده‌سازی (implement)
می‌کند
در دو حالت نخست، دستور javadoc زیرعنوان Overrides را در مستنداتِ متدِ
بازنویسی‌کننده تولید می‌کند. پیوندی به متدی که بازنویسی شده اضافه می‌شود،
چه کامنت به ارث برده شده باشد چه نشده باشد.
در حالت سوم، هنگامی که یک متد در یک کلاس مشخص، متدی را در یک رابط
پیاده‌سازی می‌کند، دستور javadoc زیرعنوان Specified by را در مستنداتِ متدِ
پیاده‌سازی‌کننده تولید می‌کند. پیوندی به متدی که پیاده‌سازی شده قرار
می‌گیرد، چه کامنت به ارث برده شده باشد چه نشده باشد.
الگوریتم کامنت‌های متد (METHOD COMMENTS ALGORITHM)
اگر متدی کامنت مستندسازی نداشته باشد، یا شامل برچسب {@inheritDoc} باشد،
دستور javadoc از الگوریتم زیر برای یافتن یک کامنت کاربردی استفاده
می‌کند. این الگوریتم طوری طراحی شده است که خاص‌ترین کامنت مستندسازیِ
قابل‌اعمال را بیابد و رابط‌ها را بر سوپرکلاس‌ها ترجیح دهد:
1. در هر رابطِ مستقیماً پیاده‌سازی‌شده (یا ارث‌بری‌شده/extended) به ترتیبی
که پس از کلمه implements (یا extends) در اعلان متد ظاهر می‌شوند،
جستجو کنید. از اولین کامنت مستندسازی یافت‌شده برای این متد استفاده
کنید.
2. اگر مرحله ۱ در یافتن کامنت مستندسازی ناموفق بود، کل این الگوریتم را
به صورت بازگشتی بر روی هر رابط مستقیماً پیاده‌سازی‌شده (یا ارث‌بری‌شده)
به همان ترتیبی که در مرحله ۱ بررسی شدند، اعمال کنید.
3. هنگامی که مرحله ۲ در یافتن کامنت مستندسازی ناموفق باشد و این
ساختار، کلاسی به غیر از کلاس Object باشد (نه یک رابط):
1. اگر سوپرکلاس دارای یک کامنت مستندسازی برای این متد است، از آن
استفاده کنید.
2. اگر مرحله ۳-الف در یافتن کامنت مستندسازی ناموفق بود، کل این
الگوریتم را به صورت بازگشتی روی سوپرکلاس اعمال کنید.
برچسب‌های جاوا داک (JAVADOC TAGS)
دستور javadoc برچسب‌های ویژه‌ای را که درون کامنت مستندسازی جاوا قرار
گرفته‌اند تجزیه می‌کند. برچسب‌های javadoc به شما امکان می‌دهند تا یک API
کامل و خوش‌قالب را به طور خودکار از کد منبع خود تولید کنید. این برچسب‌ها
با علامت اتساین (@) آغاز می‌شوند و حساس به بزرگ و کوچکی حروف هستند. آنها
باید با حروف بزرگ و کوچک دقیقاً همان‌گونه که نشان داده شده‌اند تایپ شوند.
یک برچسب باید در ابتدای خط (پس از هر فاصله ابتدایی و ستاره اختیاری)
آغاز شود، در غیر این صورت به عنوان متن در نظر گرفته می‌شود. طبق عرف،
برچسب‌های هم‌نام با هم گروه‌بندی می‌شوند؛ برای مثال، تمام برچسب‌های @see را
کنار هم قرار دهید. برای اطلاعات بیشتر، بخش «مکان‌های قابل استفاده برای
برچسب‌ها» (Where Tags Can Be Used) را ببینید.
برچسب‌ها دارای انواع زیر هستند:
• برچسب‌های بلوکی (Block tags): برچسب‌های بلوکی را تنها در بخش برچسب‌ها که
پس از توضیحات می‌آید قرار دهید. برچسب‌های بلوکی به شکل @tag هستند.
• برچسب‌های درون‌خطی (Inline tags): برچسب‌های درون‌خطی را در هر کجای
توضیحات اصلی یا در کامنت‌های برچسب‌های بلوکی قرار دهید. برچسب‌های
درون‌خطی در میان آکولادها محصور می‌شوند: {@tag}.
برای برچسب‌های سفارشی، گزینه -tag tagname:Xaoptcmf:"taghead" را ببینید.
همچنین بخش «مکان‌های قابل استفاده برای برچسب‌ها» (Where Tags Can Be Used)
را ببینید.
شرح برچسب‌ها (TAG DESCRIPTIONS)
@author name-text
معرفی‌شده در JDK 1.0
هنگامی که از گزینه -author استفاده می‌شود، یک مدخل «Author» با
متن نام مشخص‌شده به اسناد تولیدشده اضافه می‌کند. یک کامنت
مستندسازی می‌تواند شامل چندین برچسب @author باشد. شما می‌توانید در
هر برچسب @author یک نام، یا در هر برچسب چندین نام را مشخص کنید.
در حالت اول، دستور javadoc یک ویرگول (,) و یک فاصله بین نام‌ها
درج می‌کند. در حالت دوم، تمام متن بدون تجزیه شدن در سند تولیدشده
کپی می‌شود. بنابراین، اگر جداکننده نامِ بومی‌سازی‌شده دیگری به غیر
از ویرگول می‌خواهید، می‌توانید از چندین نام در یک خط استفاده کنید.
مدخل @author را در How to Write Doc Comments for the Javadoc
Tool در
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@author
ببینید.
{@code text}
معرفی‌شده در JDK 1.5
معادل با <code>{@literal}</code>.
متن را با قلم کد (code font) بدون تفسیر آن به عنوان نشانه‌گذاری
HTML یا برچسب‌های تودرتوی Javadoc نمایش می‌دهد. این امکان را به
شما می‌دهد تا به جای موجودیت‌های HTML (< و >)، از براکت‌های
شکسته معمولی (< و >) در کامنت‌های مستندسازی استفاده کنید، مانند
انواع پارامترها (<Object>)، نابرابری‌ها (3 < 4) یا فلش‌ها (<-).
برای مثال، متن کامنت مستندسازی {@code A<B>C} در صفحه HTML
تولیدشده بدون تغییر به صورت A<B>C نمایش داده می‌شود. این بدان
معنی است که <B> به عنوان پررنگ (bold) تفسیر نمی‌شود و با قلم کد
است. اگر همین عملکرد را بدون قلم کد می‌خواهید، از برچسب
{@literal} استفاده کنید.
@deprecated deprecated-text
معرفی‌شده در JDK 1.0
یادداشتی اضافه می‌کند که نشان می‌دهد این API دیگر نباید استفاده
شود (حتی اگر هنوز کار کند). دستور javadoc متن deprecated-text را
به قبل از توضیحات اصلی منتقل کرده، آن را با قلم مورب قرار می‌دهد
و پیش از آن هشداری برجسته اضافه می‌کند: Deprecated. این برچسب در
تمام کامنت‌های مستندسازی معتبر است: overview، package، class،
interface، constructor، method و field.
جمله اولِ متن منسوخ‌شده باید به کاربر بگوید که این API چه زمانی
منسوخ شده و از چه چیزی به عنوان جایگزین استفاده کند. دستور
javadoc جمله اول را در بخش خلاصه و نمایه (index) کپی می‌کند.
جملات بعدی می‌توانند دلیل منسوخ شدن آن را نیز توضیح دهند. شما
باید یک برچسب {@link} (برای Javadoc 1.2 یا بالاتر) اضافه کنید که
به API جایگزین اشاره داشته باشد.
برای منسوخ کردن یک عنصر برنامه، از برچسب حاشیه‌نویسی @deprecated
annotation استفاده کنید. بخش How and When to Deprecate APIs را
در
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/deprecation/deprecation.html
ببینید.
همچنین @deprecated را در How to Write Doc Comments for the
Javadoc Tool در
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@deprecated
ببینید.
{@docRoot}
معرفی‌شده در JDK 1.3
مسیر نسبی به دایرکتوری ریشه (مقصد) سند تولیدشده را از هر صفحه
تولیدشده نشان می‌دهد. این برچسب زمانی مفید است که بخواهید فایلی،
مانند یک صفحه کپی‌رایت یا نشان‌واره شرکت را بگنجانید که می‌خواهید
از تمام صفحات تولیدشده به آن ارجاع داده شود. پیوند دادن به صفحه
کپی‌رایت از پایین هر صفحه متداول است.
این برچسب {@docRoot} می‌تواند هم در خط فرمان و هم در کامنت
مستندسازی استفاده شود. این برچسب در تمام کامنت‌های مستندسازی
معتبر است: overview، package، class، interface، constructor،
method و field، و شامل بخش متنی هر برچسبی (مانند برچسب‌های
@return، @param و @deprecated) می‌شود.
• در خط فرمان، جایی که سربرگ، پاورقی یا پایین صفحه تعریف شده‌اند:
javadoc -bottom '<a
href="{@docRoot}/copyright.html">Copyright</a>'.
هنگامی که از برچسب {@docRoot} بدین صورت در یک makefile استفاده
می‌کنید، برخی از برنامه‌های makefile نیاز به روش خاصی برای گریز
دادن (escape کردن) کاراکترهای آکولاد {} دارند. برای مثال، نسخه
5.2 از Inprise MAKE که در Windows اجرا می‌شود به آکولاد دوتایی
نیاز دارد: {{@docRoot}}. همچنین لازم دارد تا آرگومان‌های
گزینه‌هایی مانند گزینه -bottom در علامت‌های نقل‌قول دوتایی (به
جای تکی) محصور شوند (همراه با حذف علامت‌های نقل‌قول در اطراف
آرگومان href).
• در کامنت مستندسازی:
/**
* See the <a href="{@docRoot}/copyright.html">Copyright</a>.
*/
این برچسب لازم است زیرا اسناد تولیدشده در دایرکتوری‌های
سلسله‌مراتبی قرار می‌گیرند، با عمقی به اندازه تعداد زیربسته‌ها
(subpackages). عبارت: <a href="{@docRoot}/copyright.html">
برای java/lang/Object.java به <a href="../../copyright.html">
و برای java/lang/ref/Reference.java به <a
href="../../../copyright.html"> تبدیل می‌شود.
@exception class-name description
معرفی‌شده در JDK 1.0
کاملاً مشابه برچسب @throws است. مدخل @throws class-name
description را ببینید.
{@inheritDoc}
معرفی‌شده در JDK 1.4
مستندات را از نزدیک‌ترین کلاس با قابلیت ارث‌بری یا رابط
قابل‌پیاده‌سازی در محل این برچسب به داخل کامنت مستندسازی فعلی به
ارث می‌برد (کپی می‌کند). این امکان به شما اجازه می‌دهد تا در سطوح
بالاتر درخت وراثت کامنت‌های عمومی‌تری بنویسید و در اطراف متن
کپی‌شده توضیحات اختصاصی اضافه کنید.
این برچسب تنها در این مکان‌ها درون یک کامنت مستندسازی معتبر است:
• در بلوک توضیحات اصلی یک متد. در این حالت، توضیحات اصلی از یک
کلاس یا رابط در سطوح بالاتر سلسله‌مراتب کپی می‌شود.
• در آرگومان‌های متنی برچسب‌های @return، @param و @throws متعلق به
یک متد. در این حالت، متن برچسب از برچسب متناظر در سطوح بالاتر
سلسله‌مراتب کپی می‌شود.
برای شرح نحوه یافتن کامنت‌ها در سلسله‌مراتب وراثت، بخش «وراثت کامنت متد»
(Method Comment Inheritance) را ببینید. توجه داشته باشید که اگر این
برچسب غایب باشد، کامنت طبق قوانینی که در آن بخش توضیح داده شده است، به
طور خودکار به ارث می‌رسد یا به ارث نمی‌رسد.
{@link package.class#member label}
معرفی‌شده در JDK 1.2
یک پیوند درون‌خطی با یک برچسب متنیِ قابل‌مشاهده درج می‌کند که به
مستندات بسته، کلاس، یا نام عضو مشخص‌شده از یک کلاس مرجع اشاره
دارد. این برچسب در تمام کامنت‌های مستندسازی معتبر است: overview،
package، class، interface، constructor، method و field، شامل بخش
متنی هر برچسبی مانند برچسب‌های @return، @param و @deprecated.
مدخل @link را در How to Write Doc Comments for the Javadoc Tool
در
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#{@link
ببینید.
این برچسب مشابه برچسب @see است. هر دو برچسب به مراجع یکسانی نیاز
دارند و ساختار نگارشی (syntax) یکسانی را برای
package.class#member و label می‌پذیرند. تفاوت اصلی در این است که
برچسب {@link} به جای قرار دادن پیوند در بخش «همچنین ببینید»، یک
پیوند درون‌خطی تولید می‌کند. برچسب {@link} با آکولاد باز و بسته
می‌شود تا از بقیه متن درون‌خطی جدا گردد. اگر نیاز دارید در داخل
برچسب متنی (label) از آکولاد راست (}) استفاده کنید، از نمایش
موجودیت HTML یعنی } استفاده نمایید.
هیچ محدودیتی در تعداد برچسب‌های {@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 (< و >)، از
براکت‌های شکسته (< و >) استفاده کنید، مانند انواع پارامترها
(<Object>)، نابرابری‌ها (3 < 4) یا فلش‌ها (<-). برای مثال، متن
کامنت مستندسازی {@literal A<B>C} در صفحه HTML تولیدشده در مرورگر
شما بدون تغییر به صورت A<B>C نمایش می‌یابد. عبارت <B> به عنوان
پررنگ (bold) تفسیر نمی‌شود (و با قلم کد نیز نمایش داده نمی‌شود).
اگر می‌خواهید همین عملکرد را با متن در قلم کد داشته باشید، از
برچسب {@code} استفاده کنید..TP @param parameter-name description
معرفی‌شده در JDK 1.0
پارامتری با parameter-name مشخص‌شده به همراه توضیحات تعیین‌شده به
بخش Parameters اضافه می‌کند. هنگام نوشتن کامنت مستندسازی،
می‌توانید توضیحات را در چندین خط ادامه دهید. این برچسب تنها در
کامنت مستندسازی یک متد، سازنده یا کلاس معتبر است. بخش @param را
در How to Write Doc Comments for the Javadoc Tool در آدرس
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@param
ببینید.
مقدار parameter-name می‌تواند نام یک پارامتر در متد یا سازنده، یا
نام یک پارامتر نوع (type parameter) برای یک کلاس، متد، یا سازنده
باشد. برای مشخص کردن استفاده از یک پارامتر نوع، از علامت‌های
کوچکتری/بزرگتری (< >) در اطراف نام این پارامتر استفاده کنید.
مثالی از پارامتر نوع برای یک کلاس:
/**
* @param <E> Type of element stored in a list
*/
public interface List<E> extends Collection<E> {
}
مثالی از پارامتر نوع برای یک متد:
/**
* @param string the string to be converted
* @param type the type to convert the string to
* @param <T> the type of the element
* @param <V> the value of the element
*/
<T, V extends T> V convert(String string, Class<T> type) {
}
@return description
معرفی‌شده در JDK 1.0
بخشی با عنوان Returns به همراه متن توضیحات اضافه می‌کند. این متن
باید نوع بازگشتی و محدوده مجاز مقادیر را شرح دهد. این برچسب تنها
در کامنت مستندسازی یک متد معتبر است. بخش @return را در How to
Write Doc Comments for the Javadoc Tool در آدرس
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@return
ببینید.
@see reference
معرفی‌شده در JDK 1.0
یک عنوان See Also به همراه پیوند یا مدخل متنی که به یک مرجع
اشاره دارد، اضافه می‌کند. یک کامنت مستندسازی می‌تواند شامل هر
تعداد برچسب @see باشد که همگی ذیل یک عنوان گروه‌بندی می‌شوند.
برچسب @see دارای سه حالت مختلف است. این فرم رایج‌ترین حالت است.
این برچسب در هر کامنت مستندسازی معتبر است: مرور کلی (overview)،
بسته، کلاس، رابط، سازنده، متد یا فیلد. برای قرار دادن یک پیوند
درون‌خطی در یک جمله به یک بسته، کلاس یا عضو، {@link} را ببینید.
فرم ۱. فرم برچسب @see string یک مدخل متنی برای string اضافه
می‌کند. هیچ پیوندی تولید نمی‌شود. این رشته نشان‌دهنده یک کتاب یا
مرجع دیگری برای اطلاعاتی است که از طریق URL در دسترس نیست. دستور
javadoc این حالت را با جستجوی یک علامت نقل‌قول جفتی (") به عنوان
نویسه اول، از موارد پیشین تشخیص می‌دهد. برای مثال، @see "The Java
Programming Language" که متن زیر را تولید می‌کند:
See Also:
"The Java Programming Language"
فرم ۲. فرم @see <a href="URL#value">label</a> پیوندی را به صورت
تعریف‌شده توسط URL#value اضافه می‌کند. پارامتر URL#value یک URL
نسبی یا مطلق است. دستور javadoc این حالت را با جستجوی نماد
کوچکتری (<) به عنوان نویسه اول، از سایر موارد تشخیص می‌دهد. برای
مثال، @see <a href="spec.html#section">Java Spec</a> پیوند زیر
را تولید می‌کند:
See Also:
Java Spec
فرم ۳. فرم @see package.class#member label پیوندی را به همراه یک
برچسب متنی قابل‌مشاهده اضافه می‌کند که به مستندات نام مشخص‌شده و
ارجاع‌یافته در زبان Java اشاره دارد. برچسب (label) اختیاری است.
در صورت حذف برچسب، نام به جای آن به صورت متنی قابل‌مشاهده و به
طور مناسب کوتاه‌شده نمایش داده می‌شود. از گزینه -noqualifier برای
حذف سراسری نام بسته از این متن قابل‌مشاهده استفاده کنید. زمانی از
برچسب استفاده کنید که می‌خواهید متن قابل‌مشاهده با متنِ تولیدشده به
صورت خودکار متفاوت باشد. بخش How a Name Appears را ببینید.
تنها در Java SE 1.2، نام (و نه برچسب) به طور خودکار درون
برچسب‌های HTML <code> قرار می‌گیرد. با شروع از Java SE 1.2.2،
برچسب <code> همیشه در اطراف متن قابل‌مشاهده قرار می‌گیرد، خواه از
برچسب استفاده شده باشد یا نه.
• عبارت package.class#member هر نام معتبری از عناصر برنامه است
که به آن ارجاع داده شده، مانند نام بسته، کلاس، رابط، سازنده،
متد یا فیلد، با این تفاوت که نویسه قبل از نام عضو باید علامت
نامبر ساین (#) باشد. کلاس نشان‌دهنده هر کلاس یا رابط سطح‌بالا
(top-level) یا تو در تو است. عضو نشان‌دهنده هر سازنده، متد یا
فیلد است (نه یک کلاس یا رابط تو در تو). اگر این نام در کلاس‌های
مستندسازی‌شده باشد، دستور javadoc پیوندی به آن ایجاد می‌کند.
برای ایجاد پیوند به کلاس‌های ارجاع‌یافته خارجی، از گزینه -link
استفاده کنید. برای ارجاع به مستندات نامی که متعلق به یک کلاس
ارجاع‌شده نیست، از هر یک از دو فرم دیگر برچسب @see استفاده
کنید. بخش Specify a Name را ببینید.
نکته: کلاس‌های ارجاع‌یافته خارجی کلاس‌هایی هستند که در خط فرمان
به دستور javadoc ارسال نشده‌اند. پیوندهای موجود در مستندات
تولیدشده به کلاس‌های ارجاع‌یافته خارجی، مراجع خارجی (external
references) یا پیوندهای خارجی نامیده می‌شوند. برای نمونه، اگر
دستور javadoc را فقط روی بسته java.awt اجرا کنید، هر کلاسی در
java.lang، مانند Object، یک کلاس ارجاع‌یافته خارجی خواهد بود.
از گزینه‌های -link و -linkoffline برای ایجاد پیوند به کلاس‌های
ارجاع‌یافته خارجی استفاده کنید. کامنت‌های سورس‌کد کلاس‌های
ارجاع‌یافته خارجی در هنگام اجرای دستور javadoc در دسترس نیستند.
• مقدار label متن اختیاری است که به عنوان عنوان پیوند قابل‌مشاهده
است. برچسب می‌تواند حاوی نویسه‌های فاصله سفید (white space)
باشد. در صورت حذف label، عبارت package.class.member به صورت
متناسب کوتاه‌شده نسبت به کلاس و بسته جاری نمایش داده می‌شود. بخش
How a Name Appears را ببینید.
• یک فاصله (space) جداکننده بین package.class#member و 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 می‌تواند کاملاً مقید باشد، مانند
java.lang.String#toUpperCase() یا غیرمقید باشد، مانند
String#toUpperCase() یا #toUpperCase(). اگر نام کمتر از حالت کامل مقید
باشد، دستور javadoc از ترتیب جستجوی استاندارد کامپایلر Java برای یافتن
آن استفاده می‌کند. بخش Search Order for the @see Tag را ببینید. نام
می‌تواند حاوی فاصله سفید در داخل پرانتزها باشد، مانند بین آرگومان‌های
متد. مزیت ارائه نام‌های کوتاه‌تر و تا حدی مقید این است که تایپ آنها
کوتاه‌تر بوده و آشفتگی کمتری در کد منبع وجود دارد. فهرست زیر فرم‌های
مختلف نام را نشان می‌دهد که در آن Class می‌تواند یک کلاس یا رابط باشد؛
Type می‌تواند یک کلاس، رابط، آرایه یا نوع اولیه (primitive) باشد؛ و
method می‌تواند یک متد یا سازنده باشد.
فرم‌های رایج برای @see package.class#member
ارجاع به عضوی از کلاس جاری
@see #field
@see #method(Type, Type,...)
@see #method(Type argname, Type argname,...)
@see #constructor(Type, Type,...)
@see #constructor(Type argname, Type argname,...)
ارجاع به کلاسی دیگر در بسته‌های جاری یا واردشده
@see Class#field
@see Class#method(Type, Type,...)
@see Class#method(Type argname, Type argname,...)
@see Class#constructor(Type, Type,...)
@see Class#constructor(Type argname, Type argname,...)
@see Class.NestedClass
@see Class
ارجاع به عنصری در بسته‌ای دیگر (کاملاً مقید)
@see package.Class#field
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type argname, Type argname,...)
@see package.Class#constructor(Type, Type,...)
@see package.Class#constructor(Type argname, Type argname,...)
@see package.Class.NestedClass
@see package.Class
@see package
نکاتی درباره فهرست پیشین:.TP 0.2i • مجموعه اول از ساختارها بدون کلاس یا
بسته، باعث می‌شود دستور javadoc تنها در سلسله‌مراتب کلاس فعلی جستجو کند.
این دستور عضوی از کلاس یا رابط فعلی، یکی از ابرکلاس‌ها یا ابررابط‌های آن،
یا یکی از کلاس‌ها یا رابط‌های دربرگیرنده آن را پیدا می‌کند (موارد جستجوی
۱–۳). این حالت سایر بخش‌های بسته فعلی یا بسته‌های دیگر را جستجو نمی‌کند
(موارد جستجوی ۴–۵). بخش «ترتیب جستجو برای برچسب @see» را ببینید.
• اگر هر متد یا سازنده‌ای به‌صورت یک نام بدون پرانتز وارد شود، مانند
getValue، و فیلدی با همان نام وجود نداشته باشد، دستور javadoc همچنان
پیوندی به آن متد ایجاد می‌کند. اگر این متد سربارگذاری شده باشد
(overloaded)، دستور javadoc به نخستین متدی که در جستجوی خود با آن
مواجه شود پیوند می‌دهد، که نامعین است.
• کلاس‌های تودرتو (nested classes) باید برای همه فرم‌ها به‌صورت
outer.inner مشخص شوند، نه صرفاً به‌صورت inner.
• همان‌طور که بیان شد، علامت هش (#) به جای نقطه (.) یک عضو را از کلاسش
جدا می‌کند. این امر دستور javadoc را قادر می‌سازد تا ابهامات را برطرف
کند، چرا که نقطه برای جداسازی کلاس‌ها، کلاس‌های تودرتو، بسته‌ها و
زیربسته‌ها نیز به کار می‌رود. با این حال، دستور javadoc در صورت نبود
ابهام، نقطه را به درستی تجزیه می‌کند، اما یک هشدار جهت آگاهی شما چاپ
می‌کند.
ترتیب جستجو برای برچسب @see
دستور javadoc برچسب @see را که در یک فایل مبدأ، فایل بسته یا فایل مروری
ظاهر می‌شود، پردازش می‌کند. در دو فایل آخر، باید نامی را که همراه با
برچسب @see ارائه می‌دهید، به‌طور کامل واجد شرایط (fully qualified) کنید.
در یک فایل مبدأ، می‌توانید نامی را مشخص کنید که به‌صورت کامل یا جزئی واجد
شرایط (fully qualified یا partially qualified) باشد.
در ادامه، ترتیب جستجو برای برچسب @see آمده است.
1. کلاس یا رابط فعلی.
2. هر یک از کلاس‌ها و رابط‌های دربرگیرنده، با جستجوی نزدیک‌ترین آنها در
ابتدا.
3. هر یک از ابرکلاس‌ها و ابررابط‌ها، با جستجوی نزدیک‌ترین آنها در ابتدا.
4. بسته فعلی.
5. هر یک از بسته‌ها، کلاس‌ها و رابط‌های واردشده (imported)، با جستجو به
ترتیبی که در عبارت‌های import آمده‌اند.
دستور javadoc برای هر کلاسی که با آن مواجه می‌شود، جستجو را به‌صورت
بازگشتی در موارد ۱ تا ۳ ادامه می‌دهد تا زمانی که یک تطابق پیدا کند. بدین
معنا که پس از جستجو در کلاس فعلی و کلاس دربرگیرنده آن E، پیش از کلاس‌های
دربرگیرنده E، در ابرکلاس‌های E جستجو می‌کند. در موارد ۴ و ۵، دستور
javadoc کلاس‌ها یا رابط‌های درون یک بسته را با ترتیب مشخصی جستجو نمی‌کند
(این ترتیب به کامپایلر بستگی دارد). در مورد ۵، دستور javadoc در
java.lang جستجو می‌کند زیرا توسط تمام برنامه‌ها وارد شده است.
هنگامی که دستور javadoc در یک فایل مبدأ با برچسب @see مواجه می‌شود که
نام آن به‌طور کامل واجد شرایط نشده است، نام مشخص‌شده را با همان ترتیبی
جستجو می‌کند که کامپایلر جاوا جستجو می‌کند؛ با این تفاوت که دستور javadoc
برخی از ابهامات فضای نام را تشخیص نمی‌دهد زیرا فرض می‌کند کد مبدأ عاری از
این خطاهاست. این ترتیب جستجو به‌طور رسمی در «مشخصات زبان جاوا» (Java
Language Specification) تعریف شده است. دستور javadoc آن نام را در تمامی
کلاس‌ها و بسته‌های مرتبط و واردشده جستجو می‌کند. به‌ویژه، با این ترتیب
جستجو می‌کند:
1. کلاس یا رابط فعلی.
2. هر یک از کلاس‌ها و رابط‌های دربرگیرنده، با جستجوی نزدیک‌ترین آنها در
ابتدا.
3. هر یک از ابرکلاس‌ها و ابررابط‌ها، با جستجوی نزدیک‌ترین آنها در ابتدا.
4. بسته فعلی.
5. هر یک از بسته‌ها، کلاس‌ها و رابط‌های واردشده، با جستجو به ترتیبی که در
عبارت‌های import آمده‌اند.
دستور javadoc لزوماً در زیرکلاس‌ها جستجو نمی‌کند، و در بسته‌های دیگر نیز
جستجو نخواهد کرد، حتی اگر مستندات آنها در همان نوبت اجرا تولید شود.
برای مثال، اگر برچسب @see در کلاس java.awt.event.KeyEvent باشد و به
نامی در بسته java.awt package اشاره کند، دستور javadoc در آن بسته جستجو
نخواهد کرد مگر اینکه آن کلاس آن را وارد (import) کرده باشد.
نحوه نمایش نام
اگر label حذف شود، عبارت package.class.member نمایش داده می‌شود. به‌طور
کلی، نسبت به کلاس و بسته فعلی به‌طور مناسبی کوتاه می‌شود. کوتاه شدن به
این معناست که دستور javadoc تنها حداقل نام مورد نیاز را نمایش می‌دهد.
برای مثال، اگر متد String.toUpperCase() شامل ارجاعاتی به عضوی از همان
کلاس و عضوی از یک کلاس دیگر باشد، نام کلاس تنها در مورد دوم نمایش داده
می‌شود، همان‌طور که در فهرست زیر نشان داده شده است. از گزینه -noqualifier
برای حذف سراسری نام بسته‌ها استفاده کنید.
نوع ارجاع: برچسب @see به عضوی از همان کلاس در همان بسته اشاره دارد
مثال در: @see String#toLowerCase()
نمایش به‌صورت: toLowerCase() - نام‌های بسته و کلاس حذف می‌شوند
نوع ارجاع: برچسب @see به عضوی از کلاسی دیگر در همان بسته اشاره دارد
مثال در: @see Character#toLowerCase(char)
نمایش به‌صورت: Character.toLowerCase(char) - نام بسته حذف می‌شود، نام
کلاس درج می‌شود
نوع ارجاع: برچسب @see به عضوی از کلاسی دیگر در بسته‌ای دیگر اشاره دارد
مثال در: @see java.io.File#exists()
نمایش به‌صورت: java.io.File.exists() - نام‌های بسته و کلاس درج می‌شوند
مثال‌هایی از برچسب @see
توضیحات سمت راست نشان می‌دهند که نام چگونه ظاهر می‌شود هنگامی که برچسب
@see در کلاسی در بسته‌ای دیگر قرار دارد، مانند java.applet.Applet. بخش
@see را در «نحوه نگارش توضیحات مستندسازی برای ابزار Javadoc» در
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@see
ببینید.
See also:
@see java.lang.String // String
@see java.lang.String The String class // The String class
@see String // String
@see String#equals(Object) // String.equals(Object)
@see String#equals // String.equals(java.lang.Object)
@see java.lang.Object#wait(long) // java.lang.Object.wait(long)
@see Character#MAX_RADIX // Character.MAX_RADIX
@see <a href="spec.html">Java Spec</a> // Java Spec
@see "The Java Programming Language" // "The Java Programming Language"
نکته: می‌توانید برچسب @see را گسترش دهید تا با استفاده از گزینه -link به
کلاس‌هایی که مستندسازی نمی‌شوند پیوند برقرار کنید.
@serial field-description | include | exclude
معرفی‌شده در JDK 1.2
در توضیحات مستندسازی برای یک فیلد پیش‌فرضِ قابل‌سریال‌سازی
(serializable) به کار می‌رود. بخش «مستندسازی فیلدها و داده‌های
قابل‌سریال‌سازی برای یک کلاس» را در
http://docs.oracle.com/javase/8/docs/platform/serialization/spec/serial-
arch.html#5251 ببینید.
همچنین بخش «معیارهای اوراکل برای گنجاندن کلاس‌ها در مشخصات فرم
سریال‌سازی‌شده» را در
http://www.oracle.com/technetwork/java/javase/documentation/serialized-
criteria-137781.html ببینید.
یک field-description اختیاری باید معنای فیلد را توضیح دهد و
مقادیر مجاز را فهرست کند. در صورت نیاز، توضیحات می‌تواند چندین خط
را در بر بگیرد. داکلت استاندارد (standard doclet) این اطلاعات را
به صفحه فرم سریال‌سازی‌شده اضافه می‌کند. بخش «صفحات ارجاع متقابل»
(Cross-Reference Pages) را ببینید.
اگر یک فیلد قابل‌سریال‌سازی پس از قابل‌سریال‌سازی شدنِ کلاس به آن
افزوده شده باشد، باید عبارتی به توضیحات اصلی آن اضافه شود تا
مشخص کند در کدام نسخه افزوده شده است.
آرگومان‌های include و exclude مشخص می‌کنند که آیا یک کلاس یا بسته
باید در صفحه فرم سریال‌سازی‌شده گنجانده شود یا کنار گذاشته شود.
عملکرد آنها به این صورت است:
• کلاسی با سطح دسترسی public یا protected که Serializable را
پیاده‌سازی می‌کند گنجانده می‌شود، مگر اینکه آن کلاس (یا بسته‌اش)
با برچسب @serial exclude علامت‌گذاری شده باشد.
• کلاسی با سطح دسترسی private یا package-private که Serializable
را پیاده‌سازی می‌کند کنار گذاشته می‌شود، مگر اینکه آن کلاس (یا
بسته‌اش) با برچسب @serial include علامت‌گذاری شده باشد.
برای مثال، بسته javax.swing در package.html یا package-info.java با
برچسب @serialexclude علامت‌گذاری شده است. کلاس عمومی
java.security.BasicPermission با برچسب @serial exclude علامت‌گذاری شده
است. کلاس سطح بسته java.util.PropertyPermissionCollection با برچسب
@serial include علامت‌گذاری شده است.
برچسب @serial در سطح کلاس، برچسب @serial در سطح بسته را بازنویسی
(override) می‌کند.
@serialData data-description
معرفی‌شده در JDK 1.2
از مقدار شرح داده (data description) برای مستندسازی انواع و
ترتیب داده‌ها در فرم سریال‌سازی‌شده استفاده می‌کند. این داده‌ها شامل
داده‌های اختیاری نوشته‌شده توسط متد writeObject و تمام داده‌های (از
جمله کلاس‌های پایه) نوشته‌شده توسط متد
Externalizable.writeExternal می‌شود.
برچسب @serialData می‌تواند در توضیحات مستندسازی برای متدهای
writeObject، readObject، writeExternal، readExternal،
writeReplace و readResolve استفاده شود.
@serialField field-namefield-typefield-description
معرفی‌شده در JDK 1.2
یک مؤلفه ObjectStreamField از عضو serialPersistentFields یک کلاس
Serializable را مستند می‌کند. برای هر مؤلفه ObjectStreamField از
یک برچسب @serialField استفاده کنید.
@since since-text
معرفی‌شده در JDK 1.1
یک عنوان Since با مقدار مشخص‌شده در since-text به مستندات
تولیدشده اضافه می‌کند. این متن ساختار داخلی خاصی ندارد. این برچسب
در هرگونه توضیحات مستندسازی معتبر است: بررسی اجمالی (overview)،
بسته، کلاس، رابط، سازنده، متد یا فیلد. این برچسب بدین معناست که
این تغییر یا ویژگی از زمان انتشار نرم‌افزاری که با مقدار since-
text مشخص شده وجود داشته است، برای مثال: @since 1.5.
برای کد مبدأ پلتفرم جاوا، برچسب @since نشان‌دهنده نسخه مشخصات API
پلتفرم جاوا است، که لزوماً زمان اضافه شدن کد مبدأ به پیاده‌سازی
مرجع نیست. استفاده از چند برچسب @since مجاز است و مشابه چند
برچسب @author با آنها رفتار می‌شود. در صورتی که عنصر برنامه توسط
بیش از یک API استفاده شده باشد، می‌توانید از چندین برچسب استفاده
کنید.
@throws class-namedescription
معرفی‌شده در JDK 1.2
مشابه برچسب @exception عمل می‌کند. بخش @throws را در «نحوه نگارش
توضیحات مستندسازی برای ابزار Javadoc» در
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@exception
ببینید.
برچسب @throws یک زیرعنوان Throws را همراه با متن‌های class-name و
description به مستندات تولیدشده اضافه می‌کند. مقدار class-name
نام استثنایی است که ممکن است توسط متد پرتاب شود. این برچسب تنها
در توضیحات مستندسازیِ یک متد یا سازنده معتبر است. اگر این کلاس
به‌طور کامل مشخص نشده باشد، دستور javadoc از ترتیب جستجو برای
یافتن این کلاس استفاده می‌کند. می‌توان از چندین برچسب @throws در
یک توضیح مستندسازیِ مشخص برای استثناهای یکسان یا متفاوت استفاده
کرد. بخش «ترتیب جستجو برای برچسب @see» را ببینید.
برای اطمینان از اینکه تمامی استثناهای بررسی‌شده (checked
exceptions) مستند شده‌اند، زمانی که برچسب @throws برای یک استثنا
در عبارت throws وجود نداشته باشد، دستور javadoc آن استثنا را
(بدون شرح) به خروجی HTML اضافه می‌کند، گویی که با برچسب @throws
مستندسازی شده باشد.
مستندات @throws تنها زمانی از یک متد بازنویسی‌شده (overridden) به
یک زیرکلاس کپی می‌شود که استثنا به‌طور صریح در متد بازنویسی‌شده
اعلان شده باشد. همین امر برای کپی کردن از متد یک رابط به متد
پیاده‌سازی‌کننده نیز صدق می‌کند. می‌توانید از برچسب {@inheritDoc}
برای وادار کردن برچسب @throws به ارث‌بری مستندات استفاده کنید.
{@value package.class#field}
معرفی‌شده در JDK 1.4
مقادیر ثابت را نمایش می‌دهد. هنگامی که برچسب {@value} بدون
آرگومان در توضیحات مستندسازیِ یک فیلد ایستا (static) استفاده شود،
مقدار آن ثابت را نمایش می‌دهد:
/**
* The value of this constant is {@value}.
*/
public static final String SCRIPT_START = "<script>"
هنگامی که با آرگومان package.class#field در هر توضیح مستندسازی
استفاده شود، برچسب {@value} مقدار ثابت مشخص‌شده را نمایش می‌دهد:
/**
* Evaluates the script starting with {@value #SCRIPT_START}.
*/
public String evalScript(String script) {}
آرگومان package.class#field شکلی مشابه با آرگومان برچسب @see به
خود می‌گیرد، با این تفاوت که عضو مربوطه باید یک فیلد ایستا باشد.
مقادیر این ثابت‌ها همچنین در بخش Constant Field Values در
http://docs.oracle.com/javase/8/docs/api/constant-values.html
نمایش داده می‌شوند..TP @version version-text در JDK 1.0 معرفی شد.
هنگامی که از گزینهٔ -version استفاده شود، یک زیرعنوان Version با
مقدار مشخص‌شدهٔ version-text به اسناد تولیدشده اضافه می‌کند. این
برچسب برای نگهداری شمارهٔ انتشار فعلی نرم‌افزاری که این کد بخشی از
آن است در نظر گرفته شده است، برخلاف برچسب @since که شمارهٔ
انتشاری را نگه می‌دارد که این کد در آن معرفی شده بود. مقدار
version-text ساختار داخلی خاصی ندارد. بخش @version را در «How to
Write Doc Comments for the Javadoc Tool» در
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@version
ببینید.
یک کامنت مستندسازی می‌تواند شامل چند برچسب @version باشد. در صورت
لزوم، می‌توانید برای هر برچسب @version یک شمارهٔ انتشار یا برای هر
برچسب چند شمارهٔ انتشار مشخص کنید. در حالت اول، دستور javadoc یک
کاما (,) و یک فاصله بین نام‌ها درج می‌کند. در حالت دوم، کل متن
بدون تجزیه شدن در سند تولیدشده کپی می‌شود. بنابراین، هنگامی که
می‌خواهید جداکننده‌ای بومی‌سازی‌شده به‌جز کاما داشته باشید، می‌توانید
چندین نام را در هر خط استفاده کنید.
محل استفاده از برچسب‌ها (WHERE TAGS CAN BE USED)
بخش‌های زیر توضیح می‌دهند که برچسب‌ها در کجا قابل استفاده هستند. توجه
داشته باشید که برچسب‌های زیر می‌توانند در تمامی کامنت‌های مستندسازی
استفاده شوند: @see، @since، @deprecated، {@link}، {@linkplain} و
{@docroot}.
برچسب‌های نمای کلی (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 از داکلت‌ها (doclets) برای تعیین خروجی خود استفاده می‌کند.
دستور javadoc از داکلت استاندارد پیش‌فرض استفاده می‌کند، مگر اینکه با
گزینهٔ -doclet یک داکلت سفارشی تعیین شده باشد. دستور javadoc مجموعه‌ای از
گزینه‌های خط فرمان را ارائه می‌دهد که می‌توان با هر داکلتی از آنها استفاده
کرد. این گزینه‌ها در «گزینه‌های Javadoc» شرح داده شده‌اند. داکلت استاندارد
مجموعهٔ دیگری از گزینه‌های خط فرمان را فراهم می‌کند که در «گزینه‌های داکلت
استاندارد» شرح داده شده‌اند. نام تمامی گزینه‌ها به بزرگ و کوچک بودن حروف
حساس نیست، اما آرگومان‌های آنها به حروف بزرگ و کوچک حساس هستند.
• همچنین ببینید: گزینه‌های Javadoc
• همچنین ببینید: گزینه‌های داکلت استاندارد
گزینه‌ها عبارتند از:
-1.1 || -author || -bootclasspath classpathlist || -bottom text ||
-breakiterator || -charset name || -classpath classpathlist || -d
directory || -docencoding name || -docfilesubdirs || -doclet class ||
-docletpath classpathlist || -doctitle title || -encoding || -exclude
packagename1:packagename2:... || -excludedocfilessubdir name1:name2 ||
-extdirs dirist || -footer footer || -group groupheading
packagepattern:packagepattern || -header header || -help || -helpfile
path\filename || -Jflag || -javafx ||-keywords || -link extdocURL ||
-linkoffline extdocURL packagelistLoc || -linksource || -locale
language_country_variant || -nocomment || -nodeprecated ||
-nodeprecatedlist || -nohelp || -noindex || -nonavbar || -noqualifier
all | packagename1:packagename2... || -nosince || -notimestamp ||
-notree || -overview path/filename || -package || -private ||
-protected || -public || -quiet || -serialwarn || -source release ||
-sourcepath sourcepathlist || -sourcetab tablength || -splitindex ||
-stylesheet path/filename || -subpackages package1:package2:... || -tag
tagname:Xaoptcmf:"taghead" || -taglet class || -tagletpath
tagletpathlist || -title title || -top || -use || -verbose || -version
|| -windowtitle title
گزینه‌های زیر، گزینه‌های اصلی Javadoc هستند که برای تمام داکلت‌ها در دسترس
می‌باشند. داکلت استاندارد باقی موارد را ارائه می‌دهد: -bootclasspath،
-breakiterator، -classpath، -doclet، -docletpath، -encoding، -exclude،
-extdirs، -help، -locale، -overview، -package، -private، -protected،
-public، -quiet، -source، -sourcepath، -subpackages و -verbose.
گزینه‌های JAVADOC (JAVADOC OPTIONS)
-overview path/filename
مشخص می‌کند که دستور javadoc باید متن مستندات کلی (overview) را
از فایل مبدأ مشخص‌شده توسط path/filename واکشی کرده و آن را در
صفحهٔ Overview (فایل overview-summary.html) قرار دهد. مسیر
path/filename نسبت به دایرکتوری جاری سنجیده می‌شود.
اگرچه می‌توانید از هر نام دلخواهی برای مقدار filename استفاده
کنید و آن را در هر کجای مسیر قرار دهید، اما معمول است که نام آن
را overview.html بگذارید و آن را در درخت مبدأ درون دایرکتوری‌ای
قرار دهید که شامل بالاترین دایرکتوری‌های بسته است. در این مکان،
هنگام مستندسازی بسته‌ها به هیچ مسیری نیاز نیست، زیرا گزینهٔ
-sourcepath به این فایل اشاره می‌کند.
برای مثال، اگر درخت مبدأ برای بستهٔ java.lang برابر با
/src/classes/java/lang/ باشد، می‌توانید فایل overview را در
/src/classes/overview.html قرار دهید.
بخش Real-World Examples را ببینید.
برای اطلاعات دربارهٔ فایل مشخص‌شده با path/filename، بخش Overview
Comment Files را ببینید.
صفحهٔ overview تنها زمانی ایجاد می‌شود که دو یا چند نام بسته را به
دستور javadoc ارسال کنید. برای توضیحات بیشتر، بخش HTML Frames را
ببینید. عنوان صفحهٔ overview توسط -doctitle تنظیم می‌شود.
-Xdoclint:(all|none|[-]<group>)
هشدارهایی را برای ارجاعات نادرست، عدم دسترس‌پذیری (accessibility)
و کامنت‌های مفقود Javadoc گزارش می‌کند، و خطاهایی را برای نحو
(syntax) نامعتبر Javadoc و برچسب‌های مفقود HTML گزارش می‌دهد.
این گزینه به دستور javadoc امکان می‌دهد تمام کامنت‌های مستنداتی
گنجانده‌شده در خروجی تولیدشده را بررسی کند. طبق معمول، می‌توانید
با گزینه‌های استاندارد -public، -protected، -package و -private
مواردی را که باید در خروجی تولیدشده قرار گیرند انتخاب کنید.
هنگامی که -Xdoclint فعال باشد، مشکلات را با پیام‌هایی مشابه با
دستور javac گزارش می‌دهد. دستور javadoc یک پیام، رونوشتی از خط
مبدأ و یک علامت هشتک (caret) چاپ می‌کند که به موقعیت دقیق خطای
شناسایی‌شده اشاره دارد. پیام‌ها بسته به شدت مشکل و احتمال ایجاد
خطا در صورت اعتبارسنجی مستندات تولیدشده توسط یک validator، ممکن
است هشدار یا خطا باشند. برای نمونه، ارجاعات نادرست یا کامنت‌های
مفقود Javadoc باعث نمی‌شوند که دستور javadoc کدهای HTML نامعتبر
تولید کند، بنابراین این موارد به عنوان هشدار گزارش می‌شوند.
خطاهای نحوی یا برچسب‌های پایانی مفقود در HTML باعث می‌شوند که
دستور javadoc خروجی نامعتبر تولید کند، بنابراین این موارد به
عنوان خطا گزارش می‌شوند.
به‌طور پیش‌فرض، گزینهٔ -Xdoclint فعال است. آن را با گزینهٔ
-Xdoclint:none غیرفعال کنید.
آنچه را که گزینهٔ -Xdoclint گزارش می‌دهد با گزینه‌های زیر تغییر
دهید:
• -Xdoclint none : غیرفعال کردن گزینهٔ -Xdoclint
• -Xdoclintgroup : فعال کردن بررسی‌های group
• -Xdoclint all : فعال کردن تمام گروه‌های بررسی
• -Xdoclint all,-group : فعال کردن همهٔ بررسی‌ها به جز group
متغیر group یکی از مقادیر زیر را می‌پذیرد:
• accessibility : بررسی مشکلاتی که توسط یک ابزار ارزیابی
دسترس‌پذیری شناسایی می‌شوند (برای نمونه، عدم تعیین مشخصه‌های
caption یا summary در یک برچسب <table>).
• html : شناسایی مشکلات سطح بالای HTML، مانند قرار دادن عناصر
بلوکی درون عناصر درون‌خطی (inline)، یا نبستن عناصری که نیازمند
برچسب پایانی هستند. این قواعد از مشخصات HTML 4.01 برگرفته
شده‌اند. این نوع بررسی دستور javadoc را قادر می‌سازد مشکلات HTML
را که ممکن است بسیاری از مرورگرها نادیده بگیرند، شناسایی کند.
• missing : بررسی کامنت‌ها یا تگ‌های مفقود Javadoc (برای نمونه،
کامنت یا کلاس مفقود، یا یک تگ مفقود @return یا تگ مشابه روی یک
متد).
• reference : بررسی مشکلات مربوط به ارجاعات به عناصر Java API از
برچسب‌های Javadoc (برای نمونه، آیتم یافت‌نشده در @see، یا نام
نادرست پس از @param).
• syntax : بررسی مشکلات سطح پایین مانند براکت‌های شکسته
فرارنیافته (< و >) و علامت‌های امپرسند (&) و برچسب‌های نامعتبر
Javadoc.
می‌توانید گزینهٔ -Xdoclint را چندین بار مشخص کنید تا بررسی خطاها و
هشدارها در چند دسته فعال شود. همچنین، می‌توانید چندین دستهٔ خطا و هشدار
را با استفاده از گزینه‌های پیش‌گفته مشخص کنید. برای مثال، از هر یک از
دستورهای زیر برای بررسی مشکلات HTML، نحو و دسترس‌پذیری در فایل filename
استفاده کنید.
javadoc -Xdoclint:html -Xdoclint:syntax -Xdoclint:accessibility filename
javadoc -Xdoclint:html,syntax,accessibility filename
نکته: دستور javadoc جامعیت این بررسی‌ها را تضمین نمی‌کند. به‌ویژه، این
ابزار یک بررسی‌کنندهٔ کامل تطابق با HTML نیست. هدف گزینهٔ -Xdoclint این
است که دستور javadoc را قادر سازد بخش عمده‌ای از خطاهای رایج را گزارش
کند.
دستور javadoc تلاشی برای اصلاح ورودی نامعتبر نمی‌کند، بلکه صرفاً آن را
گزارش می‌دهد.
-public
تنها کلاس‌ها و اعضای public را نشان می‌دهد.
-protected
تنها کلاس‌ها و اعضای protected و public را نشان می‌دهد. این حالت
پیش‌فرض است.
-package
تنها کلاس‌ها و اعضای package، protected و public را نشان می‌دهد.
-private
تمام کلاس‌ها و اعضا را نشان می‌دهد.
-help
راهنمای برخط را نمایش می‌دهد که تمام گزینه‌های خط فرمان javadoc و
doclet را فهرست می‌کند.
-doclet class
فایل کلاسی را مشخص می‌کند که داکلتِ مورد استفاده در تولید مستندات
را راه‌اندازی می‌کند. از نام کاملاً مشخص (fully qualified name)
استفاده کنید. این داکلت محتوا را تعیین کرده و خروجی را قالب‌بندی
می‌کند. اگر از گزینهٔ -doclet استفاده نشود، دستور javadoc از داکلت
استاندارد برای تولید قالب پیش‌فرض HTML استفاده می‌کند. این کلاس
باید شامل متد start(Root) باشد. مسیر رسیدن به این کلاس آغازین
توسط گزینهٔ -docletpath تعیین می‌شود. بخش Doclet Overview را در
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/overview.html
ببینید.
-docletpath classpathlist
مسیر فایل کلاس آغازین داکلت (مشخص‌شده با گزینهٔ -doclet) و هر فایل
JAR که به آن وابسته است را مشخص می‌کند. اگر فایل کلاس آغازین درون
یک فایل JAR باشد، این گزینه مسیر منتهی به آن فایل JAR را مشخص
می‌کند. می‌توانید یک مسیر مطلق یا مسیری نسبت به دایرکتوری جاری
مشخص کنید. اگر classpathlist شامل چندین مسیر یا فایل JAR باشد،
باید آنها را در Oracle Solaris با دونقطه (:) و در Windows با
نقطه‌ویرگول (;) از یکدیگر جدا کرد. زمانی که کلاس آغازین داکلت از
قبل در مسیر جست‌وجو قرار داشته باشد، نیازی به این گزینه نیست. بخش
Doclet Overview را در
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/overview.html
ببینید.
-1.1
از Javadoc 1.4 بدون هیچ جایگزینی حذف شده است. این گزینه مستنداتی
با ظاهر و قابلیت‌های مستندات تولیدشده توسط Javadoc 1.1 ایجاد
می‌کرد (این گزینه هرگز از کلاس‌های تودرتو پشتیبانی نکرد). اگر به
این گزینه نیاز دارید، به جای آن از Javadoc 1.2 یا 1.3 استفاده
کنید.
-source release
نسخهٔ کد منبع پذیرفته‌شده را مشخص می‌کند. مقادیر زیر برای پارامتر
release مجاز هستند. از مقدار release متناظر با مقداری که هنگام
کامپایل کد با دستور javac استفاده می‌کنید بهره ببرید.
• مقدار انتشار: 1.5. دستور javadoc کدهای شامل جنریک‌ها (generics)
و سایر ویژگی‌های زبان معرفی‌شده در JDK 1.5 را می‌پذیرد. هنگامی که
از گزینهٔ -source استفاده نشود، کامپایلر رفتار 1.5 را به‌طور
پیش‌فرض در نظر می‌گیرد.
• مقدار انتشار: 1.4. دستور javadoc کدهای شامل assertionها را که
در JDK 1.4 معرفی شدند می‌پذیرد.
• مقدار انتشار: 1.3. دستور javadoc از assertionها، جنریک‌ها یا
سایر ویژگی‌های زبان معرفی‌شده پس از JDK 1.3 پشتیبانی نمی‌کند.
-sourcepath sourcepathlist
مسیرهای جست‌وجو را برای یافتن فایلهای مبدأ هنگام ارسال نام بسته‌ها
یا گزینهٔ -subpackages به دستور javadoc مشخص می‌کند. چندین مسیر را
با دونقطه (:) از یکدیگر جدا کنید. دستور javadoc تمام
زیردایرکتوری‌های مسیرهای مشخص‌شده را جست‌وجو می‌کند. توجه داشته
باشید که این گزینه نه تنها برای یافتن محل فایلهای مبدأ در حال
مستندسازی، بلکه برای یافتن فایلهای مبدأیی که مستندسازی نمی‌شوند
اما کامنت‌های آنها توسط فایلهای مبدأ تحت مستندسازی به ارث برده
می‌شود نیز به کار می‌رود.
تنها زمانی می‌توانید از گزینهٔ -sourcepath استفاده کنید که نام
بسته‌ها را به دستور javadoc ارسال می‌کنید. این گزینه فایلهای مبدأ
ارائه‌شده به دستور javadoc را مکان‌یابی نمی‌کند. برای مشخص کردن محل
فایلهای مبدأ، به آن دایرکتوری بروید یا همان‌طور که در بخش
Document One or More Classes نشان داده شده است، مسیر را قبل از
هر فایل درج کنید. اگر -sourcepath را نادیده بگیرید، دستور
javadoc از مسیر کلاس برای یافتن فایلهای مبدأ استفاده می‌کند (به
-classpath مراجعه کنید). مقدار پیش‌فرض -sourcepath همان مقدار
مسیر کلاس (class path) است. اگر -classpath درج نشود و نام بسته‌ها
را به دستور javadoc ارسال کنید، دستور javadoc در دایرکتوری جاری
و زیردایرکتوری‌های آن به جست‌وجوی فایلهای مبدأ می‌پردازد.
مقدار sourcepathlist را روی دایرکتوری ریشهٔ درخت مبدأ برای بسته‌ای
که مستند می‌کنید قرار دهید.
برای مثال، فرض کنید می‌خواهید بسته‌ای با نام com.mypackage را
مستندسازی کنید که فایلهای مبدأ آن در مسیر
/home/user/src/com/mypackage/*.java قرار دارند. مقدار sourcepath
را برابر با /home/user/src (دایرکتوری شامل com\mypackage) تعیین
کرده و سپس نام بسته را به‌صورت زیر ارائه دهید:
javadoc -sourcepath /home/user/src/ com.mypackage
توجه داشته باشید که اگر مقدار sourcepath و نام بسته را به هم
متصل کنید و نقطه را به یک اسلش (/) تغییر دهید، مسیر کامل منتهی
به بسته را خواهید داشت:
/home/user/src/com/mypackage
برای اشاره به دو مسیر مبدأ:
javadoc -sourcepath /home/user1/src:/home/user2/src com.mypackage
-classpath classpathlist
مسیرهایی را مشخص می‌کند که دستور javadoc در آنها به دنبال کلاس‌های
ارجاع‌شده می‌گردد. این‌ها کلاس‌های مستندشده به‌علاوهٔ هر کلاسی هستند
که توسط آن کلاس‌ها ارجاع داده شده‌اند. چندین مسیر را با دونقطه (:)
جدا کنید. دستور javadoc تمام زیردایرکتوری‌های مسیرهای مشخص‌شده را
جست‌وجو می‌کند. برای تعیین مقدار classpathlist، از دستورالعمل‌های
موجود در مستندات مسیر کلاس (class path) پیروی کنید.
اگر -sourcepath را نادیده بگیرید، دستور javadoc از -classpath
برای یافتن فایلهای مبدأ و فایلهای کلاس استفاده می‌کند (جهت
سازگاری با نسخه‌های پیشین). اگر می‌خواهید فایلهای مبدأ و کلاس را
در مسیرهای جداگانه جست‌وجو کنید، از هر دو گزینهٔ -sourcepath و
-classpath استفاده نمایید.
برای مثال، اگر می‌خواهید com.mypackage را مستندسازی کنید که
فایلهای مبدأ آن در دایرکتوری /home/user/src/com/mypackage قرار
دارند، و این بسته به کتابخانه‌ای در /home/user/lib وابسته است، از
دستور زیر استفاده کنید:
javadoc -sourcepath /home/user/lib -classpath /home/user/src com.mypackage
مشابه سایر ابزارها، اگر -classpath را مشخص نکنید، دستور javadoc
در صورت تنظیم بودن متغیر محیطی CLASSPATH از آن استفاده می‌کند.
اگر هیچ‌یک تنظیم نشده باشند، دستور javadoc به دنبال کلاس‌ها در
دایرکتوری جاری می‌گردد.
برای شرح دقیق نحوهٔ استفادهٔ دستور javadoc از -classpath برای
یافتن کلاس‌های کاربر در ارتباط با کلاس‌های افزونه (extension) و
کلاس‌های خودراه‌انداز (bootstrap)، بخش How Classes Are Found را در
http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html
ببینید.
عنصری در مسیر کلاس که شامل نام پایهٔ * باشد، معادل تعیین فهرستی
از تمام فایلهای درون آن دایرکتوری با پسوند .jar یا .JAR در نظر
گرفته می‌شود.
برای مثال، اگر دایرکتوری mydir حاوی a.jar و b.JAR باشد، عنصر
مسیر کلاس foo/* به A.jar:b.JAR بسط داده می‌شود، جز اینکه ترتیب
فایلهای JAR نامشخص است. تمام فایلهای JAR درون دایرکتوری مشخص‌شده،
از جمله فایلهای پنهان، در این فهرست قرار می‌گیرند. یک مدخل در
مسیر کلاس که شامل * باشد، به فهرستی از تمام فایلهای jar در
دایرکتوری جاری بسط می‌یابد. متغیر محیطی CLASSPATH نیز به همین
صورت بسط داده می‌شود. هرگونه بسط نویسه‌های عام (wildcard) در مسیر
کلاس قبل از شروع به کار ماشین مجازی جاوا (JVM) رخ می‌دهد. هیچ
برنامهٔ جاوایی هرگز نویسه‌های عام بسط‌نیافته را نمی‌بیند مگر از طریق
پرس‌وجو از محیط، برای نمونه با فراخوانی
System.getenv("CLASSPATH")..TP -subpackages
package1:package2:...
مستندات را از فایلهای منبع در بسته‌های مشخص‌شده و به‌صورت بازگشتی
در زیربسته‌های آنها تولید می‌کند. این گزینه زمانی که زیربسته‌های
جدیدی را به کد منبع اضافه می‌کنید مفید است، زیرا آنها به‌طور
خودکار گنجانده می‌شوند. هر آرگومان بسته، هر زیربستهٔ سطح بالا
(مانند java) یا یک بستهٔ کامل (مانند javax.swing) است که نیازی به
داشتن فایلهای منبع ندارد. آرگومان‌ها در تمام سیستم‌های عامل با
دونقطه (:) از یکدیگر جدا می‌شوند. نویسه‌های عام (Wild cards) مجاز
نیستند. از -sourcepath برای مشخص کردن محل یافتن بسته‌ها استفاده
کنید. این گزینه فایلهای منبعی را که در درخت منبع قرار دارند اما
متعلق به بسته‌ها نیستند پردازش نمی‌کند. بخش Process Source Files
را ببینید.
برای مثال، دستور زیر مستندات مربوط به بسته‌هایی با نام java و
javax.swing و تمام زیربسته‌های آنها را تولید می‌کند.
javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing
-exclude packagename1:packagename2:...
به‌طور قطعی و بی‌قیدوشرط، بسته‌های مشخص‌شده و زیربسته‌های آنها را از
فهرستی که توسط -subpackages ساخته شده مستثنی می‌کند. این گزینه آن
بسته‌ها را حتی در صورتی که توسط گزینهٔ -subpackages پیشین یا پسین
دیگری گنجانده شده باشند، حذف می‌کند.
مثال زیر بسته‌های java.io، java.util و java.math (در کنار سایر
بسته‌ها) را شامل می‌شود، اما بسته‌هایی را که ریشه در java.net و
java.lang دارند مستثنی می‌سازد. توجه داشته باشید که این مثال
java.lang.ref را که یک زیربسته از java.lang است، مستثنی می‌کند.
javadoc -sourcepath /home/user/src -subpackages java -exclude
java.net:java.lang
-bootclasspath classpathlist
مسیرهایی را مشخص می‌کند که کلاس‌های راه‌اندازی (boot classes) در آن
قرار دارند. این‌ها معمولاً کلاس‌های پلتفرم جاوا هستند. مقدار
bootclasspath بخشی از مسیر جستجویی است که دستور javadoc برای
جستجوی فایلهای منبع و فایلهای کلاس استفاده می‌کند. برای اطلاعات
بیشتر، بخش How Classes Are Found را در
<http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html>
ببینید.
دایرکتوری‌ها را در پارامترهای classpathlist برای Windows با
نقطه-ویرگول (;) و برای Oracle Solaris با دونقطه (:) جدا کنید.
-extdirs dirist
دایرکتوری‌هایی را مشخص می‌کند که کلاس‌های افزونه (extension
classes) در آن قرار دارند. این‌ها کلاس‌هایی هستند که از سازوکار
افزونه جاوا (Java Extension) بهره می‌برند. گزینهٔ extdirs بخشی از
مسیر جستجویی است که دستور javadoc برای یافتن فایلهای منبع و کلاس
به کار می‌برد. برای اطلاعات بیشتر گزینهٔ -classpath را ببینید.
دایرکتوری‌ها را در dirlist با نقطه-ویرگول (;) برای Windows و با
دونقطه (:) برای Oracle Solaris از هم جدا کنید.
-verbose
پیام‌های با جزئیات بیشتری را در هنگام اجرای دستور javadoc ارائه
می‌دهد. بدون گزینهٔ verbose، پیام‌ها تنها برای بارگذاری فایلهای
منبع، تولید مستندات (یک پیام به ازای هر فایل منبع) و مرتب‌سازی
نمایش می‌یابند. گزینهٔ verbose موجب چاپ پیام‌های اضافی می‌شود که مدت
زمان لازم (به میلی‌ثانیه) را برای تجزیهٔ هر فایل منبع جاوا مشخص
می‌کنند.
-quiet
پیام‌ها را قطع می‌کند تا فقط هشدارها و خطاها نمایش داده شوند و
بررسی آنها آسان‌تر شود. این گزینه همچنین رشتهٔ version را پنهان
می‌سازد.
-breakiterator
از مرز جملهٔ بین‌المللی‌شدهٔ java.text.BreakIterator برای تعیین
انتهای جملهٔ اول در توضیحات اصلی یک بسته، کلاس یا عضو برای زبان
انگلیسی استفاده می‌کند. سایر محلی‌سازی‌ها از پیش به جای الگوریتم
خاص زبان انگلیسی، از کلاس BreakIterator استفاده می‌کنند. اولین
جمله در خلاصهٔ بسته، کلاس یا عضو و در نمایهٔ الفبایی کپی می‌شود. از
نسخهٔ JDK 1.2 به بعد، کلاس BreakIterator برای تعیین انتهای جمله
برای تمام زبان‌ها به جز انگلیسی استفاده می‌شود. بنابراین، گزینهٔ
-breakiterator از نسخهٔ 1.2 به بعد برای هیچ زبانی به جز انگلیسی
اثری ندارد. زبان انگلیسی الگوریتم پیش‌فرض خاص خود را دارد:
• الگوریتم پیش‌فرض شکست جمله در انگلیسی. در نقطه به‌همراه یک فاصله
یا یک برچسب بلوکی HTML مانند <P> متوقف می‌شود.
• الگوریتم شکست جملهٔ Breakiterator. در نقطه، علامت سؤال یا علامت
تعجب که پس از آن یک فاصله و کلمه‌ای با حرف بزرگ باشد متوقف
می‌شود. این کار برای پشتیبانی از بیشتر کلمات اختصاری است (مانند
"The serial no. is valid"، ولی موردی مانند "Mr. Smith" را
مدیریت نمی‌کند). گزینهٔ -breakiterator روی برچسب‌های HTML یا
جملاتی که با اعداد یا نمادها شروع می‌شوند متوقف نمی‌شود.
الگوریتم در آخرین نقطه در ../filename، حتی اگر درون یک برچسب
HTML باشد، متوقف می‌شود.
در Java SE 1.5 پیام‌های هشدار گزینهٔ -breakiterator حذف شده‌اند و الگوریتم
پیش‌فرض شکست جمله بدون تغییر باقی مانده است. اگر کد منبع خود را برای حذف
هشدارهای گزینهٔ -breakiterator در Java SE 1.4.x دستکاری نکرده‌اید، نیازی
به انجام کاری ندارید. این هشدارها از نسخهٔ Java SE 1.5.0 برطرف شده‌اند.
-locale language_country_variant
محلی‌سازی (locale) مورد استفاده توسط دستور javadoc را هنگام تولید
مستندات مشخص می‌کند. این آرگومان نام locale است، همان‌گونه که در
مستندات java.util.Locale شرح داده شده، مانند en_US (انگلیسی،
ایالات متحده) یا en_US_WIN (گونهٔ Windows).
نکته: گزینهٔ -locale باید جلوتر (در سمت چپ) تمام گزینه‌های
ارائه‌شده توسط doclet استاندارد یا هر doclet دیگری قرار گیرد. در
غیر این صورت، نوارهای ناوبری به زبان انگلیسی نمایش داده می‌شوند.
این تنها گزینهٔ خط فرمان است که به ترتیب قرارگیری وابسته است. بخش
Standard Doclet Options را ببینید.
تعیین محلی‌سازی موجب می‌شود دستور javadoc فایلهای منبع (resource
files) آن locale را برای پیام‌هایی چون رشته‌های نوار ناوبری،
سرتیترهای فهرست‌ها و جدول‌ها، محتوای فایل راهنما، کامنت‌های فایل
stylesheet.css و غیره برگزیند. این گزینه همچنین ترتیب مرتب‌سازی
برای فهرست‌های الفبایی و جداکنندهٔ جملات را برای تعیین انتهای
اولین جمله مشخص می‌سازد. گزینهٔ -locale تعیین‌کنندهٔ locale متن
کامنت‌های مستنداتی موجود در فایلهای منبع کلاس‌های مستندشده نیست.
-encoding
نام کدگذاری (encoding) فایلهای منبع را مشخص می‌کند، مانند
EUCJIS/SJIS. در صورت عدم تعیین این گزینه، مبدل پیش‌فرض پلتفرم
استفاده می‌شود. همچنین گزینه‌های -docencoding name و -charset name
را ببینید.
-Jflag
پرچم flag را مستقیماً به محیط زمان اجرای جاوا (JRE) که دستور
javadoc را اجرا می‌کند ارسال می‌نماید. برای نمونه، اگر بخواهید
اطمینان حاصل کنید که سیستم ۳۲ مگابایت حافظه برای پردازش مستندات
تولیدشده اختصاص می‌دهد، گزینهٔ -Xmx را بدین صورت فراخوانی می‌کنید:
javadoc -J-Xmx32m -J-Xms32m com.mypackage. توجه داشته باشید که
-Xms اختیاری است زیرا صرفاً اندازهٔ حافظهٔ اولیه را تعیین می‌کند، که
این ویژگی زمانی که حداقل حافظهٔ مورد نیاز را می‌دانید کاربرد دارد.
بین J و flag نباید هیچ فاصله‌ای وجود داشته باشد.
برای اطلاع از نسخهٔ دستور javadoc که از آن استفاده می‌کنید، گزینهٔ
-version را به کار ببرید. شماره نسخهٔ doclet استاندارد در خروجی
آن نمایش می‌یابد. بخش Running the Javadoc Command را ببینید.
javadoc -J-version
java version "1.7.0_09"
Java(TM) SE Runtime Environment (build 1.7.0_09-b05)
Java HotSpot(TM) 64-Bit Server VM (build 23.5-b02, mixed mode)
-javafx
مستندات HTML را با بهره‌گیری از افزونه‌های JavaFX روی doclet
استاندارد تولید می‌کند. مستندات تولیدشده علاوه بر سایر بخش‌های
خلاصهٔ ایجادشده توسط doclet استاندارد جاوا، شامل یک بخش خلاصه
ویژگی (Property Summary) نیز خواهد بود. ویژگی‌های فهرست‌شده به
بخش‌های متدهای getter و setter مربوط به هر ویژگی پیوند دارند.
اگر کامنت‌های مستنداتی به‌طور صریح برای متدهای getter و setter
نوشته نشده باشد، کامنت‌های مستندات متد ویژگی به‌طور خودکار به
مستندات تولیدشده برای این متدها رونوشت می‌شود. این گزینه همچنین
یک برچسب جدید به نام @defaultValue اضافه می‌کند که امکان
مستندسازی مقدار پیش‌فرض یک ویژگی را فراهم می‌سازد.
مثال:
javadoc -javafx MyClass.java -d testdir
گزینه‌های استاندارد DOCLET (STANDARD DOCLET OPTIONS)
-d directory
دایرکتوری مقصدی را مشخص می‌کند که دستور javadoc فایلهای HTML
تولیدشده را در آن ذخیره می‌نماید. در صورت حذف گزینهٔ -d، فایلها در
دایرکتوری جاری ذخیره می‌شوند. مقدار directory می‌تواند مطلق یا
نسبت به دایرکتوری کاری فعلی باشد. از نسخهٔ Java SE 1.4، دایرکتوری
مقصد در زمان اجرای دستور javadoc به‌طور خودکار ساخته می‌شود.
برای مثال، دستور زیر مستندات بستهٔ com.mypackage را تولید کرده و
نتایج را در دایرکتوری /user/doc/ ذخیره می‌کند: javadoc -d
/user/doc/ com.mypackage.
-use
یک برگهٔ Use (کاربرد) برای هر کلاس و بستهٔ مستندشده ایجاد می‌کند.
این صفحه مشخص می‌کند که چه بسته‌ها، کلاس‌ها، متدها، سازنده‌ها و
فیلدهایی از هر API کلاس یا بستهٔ مشخص‌شده استفاده می‌کنند. به عنوان
نمونه برای کلاس C، مواردی که از کلاس C استفاده می‌کنند شامل
زیرکلاس‌های C، فیلدهای تعریف‌شده از نوع C، متدهایی که مقدار
بازگشتی آنها C است و متدها و سازنده‌هایی با پارامترهایی از نوع C
خواهد بود. برای مثال، می‌توانید به برگهٔ Use برای نوع String نگاه
کنید. از آنجا که متد getName در کلاس java.awt.Font نوع String
برمی‌گرداند، این متد از String استفاده می‌کند و در نتیجه در برگهٔ
Use برای String نمایش می‌یابد. این ویژگی تنها استفاده‌ها از API را
مستند می‌کند، نه پیاده‌سازی را. هنگامی که یک متد در پیاده‌سازی خود
از String استفاده می‌کند، اما رشته‌ای به عنوان آرگومان دریافت
نکرده یا آن را برنمی‌گرداند، این مورد به عنوان استفاده از String
لحاظ نمی‌شود. برای دسترسی به صفحهٔ Use تولیدشده، به صفحهٔ کلاس یا
بسته رفته و روی پیوند Use در نوار ناوبری کلیک کنید.
-version
متن @version را در اسناد تولیدشده قرار می‌دهد. این متن به‌طور
پیش‌فرض حذف می‌شود. برای یافتن نسخهٔ مورد استفادهٔ دستور javadoc، از
گزینهٔ -J-version استفاده کنید.
-author
متن @author را در اسناد تولیدشده قرار می‌دهد.
-splitindex
فایل نمایه را به چندین فایل، بر اساس حروف الفبا، یک فایل برای هر
حرف، به‌علاوهٔ یک فایل برای هر مدخل نمایه‌ای که با نمادهای غیرحرفی
آغاز می‌شود تقسیم می‌کند.
-windowtitle title
عنوانی را برای قرار گرفتن در برچسب HTML <title> مشخص می‌کند. متنی
که در برچسب title تعیین می‌شود در عنوان پنجره و در نشانک‌های
مرورگر که کاربران برای این صفحه می‌سازند نمایش داده می‌شود. این
عنوان نباید حاوی برچسب‌های HTML باشد زیرا مرورگر آنها را به‌درستی
تفسیر نمی‌کند. برای هر علامت نقل‌قول درونی در برچسب title از
نویسه‌های گریز (escape) استفاده کنید. اگر گزینهٔ -windowtitle حذف
شود، دستور javadoc از مقدار گزینهٔ -doctitle برای -windowtitle
استفاده می‌کند. برای مثال، javadoc -windowtitle "Java SE
Platform" com.mypackage.
-doctitle title
عنوانی را برای قرار گرفتن در نزدیکی بالای فایل خلاصهٔ نمای کلی
مشخص می‌کند. متنی که در برچسب title مشخص می‌شود، به عنوان یک
سرتیتر سطح‌یک و وسط‌چین مستقیماً در زیر نوار ناوبری بالایی قرار
می‌گیرد. برچسب title می‌تواند شامل برچسب‌های HTML و فاصله باشد، اما
در این صورت، باید عنوان را در علامت نقل‌قول محصور کنید. علامت‌های
نقل‌قول درونی در برچسب title باید گریز داده شوند. برای مثال:
javadoc -header "<b>Java Platform </b><br>v1.4" com.mypackage.
-title title
دیگر وجود ندارد. این گزینه فقط در نسخه‌های بتای Javadoc 1.2 وجود
داشت و به -doctitle تغییر نام پیدا کرد. این تغییر نام انجام شد
تا مشخص شود این گزینه عنوان سند را تعیین می‌کند، نه عنوان پنجره
را.
-header header
متن سربرگ را برای قرار گرفتن در بالای هر فایل خروجی مشخص می‌کند.
سربرگ در سمت راست نوار ناوبری بالایی قرار می‌گیرد. مقدار header
می‌تواند حاوی برچسب‌های HTML و فاصله باشد، اما در این حالت باید در
علامت نقل‌قول قرار گیرد. برای علامت‌های نقل‌قول درونی در یک سربرگ
از نویسه‌های گریز استفاده کنید. برای مثال: javadoc -header
"<b>Java Platform </b><br>v1.4" com.mypackage.
-footer footer
متن پاورقی را برای قرار گرفتن در پایین هر فایل خروجی مشخص می‌کند.
مقدار footer در سمت راست نوار ناوبری پایینی قرار می‌گیرد. مقدار
footer می‌تواند شامل برچسب‌های HTML و فاصله باشد، اما در این صورت
باید درون علامت‌های نقل‌قول قرار گیرد. برای هر نقل‌قول درونی در
پاورقی از نویسه‌های گریز استفاده کنید.
-top
متنی را برای قرار گرفتن در بالای هر فایل خروجی مشخص می‌کند.
-bottom text
متنی را برای قرار گرفتن در پایین هر فایل خروجی مشخص می‌کند. این
متن در پایین برگه، در زیر نوار ناوبری پایینی قرار می‌گیرد. متن
می‌تواند شامل برچسب‌های HTML و فاصله باشد، اما در این حالت باید در
علامت نقل‌قول قرار داده شود. برای هر علامت نقل‌قول درونی در متن از
نویسه‌های گریز استفاده کنید.
-link extdocURL
پیوندهایی به مستندات موجودِ تولیدشده توسط Javadoc برای کلاس‌های
مرجع خارجی ایجاد می‌کند. آرگومان extdocURL نشانی URL مطلق یا نسبی
دایرکتوری‌ای است که مستندات خارجی ساخته‌شده توسط Javadoc را در خود
دارد. می‌توانید چندین گزینهٔ -link را در یک اجرای دستور javadoc
برای پیوند دادن به چندین سند مشخص کنید.
فایل package-list باید در این دایرکتوری یافت شود (در غیر این
صورت، از گزینهٔ -linkoffline استفاده کنید). دستور javadoc نام
بسته‌ها را از فایل package-list می‌خواند و به آن بسته‌ها در آن
نشانی URL پیوند ایجاد می‌کند. هنگامی که دستور javadoc اجرا می‌شود،
مقدار extdocURL در پیوندهای <A HREF> ساخته‌شده رونوشت می‌شود.
بنابراین، extdocURL باید نشانی دایرکتوری باشد، نه یک فایل. شما
می‌توانید از یک پیوند مطلق برای extdocURL استفاده کنید تا اسناد
شما امکان پیوند به سندی روی هر وب‌سایتی را داشته باشند، یا
می‌توانید از پیوند نسبی برای پیوند تنها به یک موقعیت مکانی نسبی
بهره بگیرید. در صورت استفاده از پیوند نسبی، مقداری که ارائه
می‌دهید باید مسیر نسبی از دایرکتوری مقصد (مشخص‌شده با گزینهٔ -d) به
دایرکتوری حاوی بسته‌های مورد پیوند باشد. هنگام تعیین پیوند مطلق،
معمولاً از پیوند HTTP استفاده می‌شود. با این حال، اگر می‌خواهید به
سیستم فایلی که فاقد وب‌سرور است پیوند دهید، می‌توانید از پیوند
file استفاده کنید. پیوند file را تنها زمانی به کار ببرید که همهٔ
افرادی که به مستندات تولیدشده دسترسی دارند، در سیستم فایل یکسانی
مشترک باشند. در تمامی موارد و در تمامی سیستم‌های عامل، از ممیز
(اسلش) به عنوان جداکننده استفاده کنید، خواه URL مطلق باشد یا
نسبی، و همان‌طور که در یادداشت URL: Uniform Resource Locators در
<http://www.ietf.org/rfc/rfc1738.txt> مشخص شده است، از http: یا
file: استفاده کنید.
-link http://<host>/<directory>/<directory>/.../<name>
-link file://<host>/<directory>/<directory>/.../<name>
-link <directory>/<directory>/.../<name>
تفاوت‌های بین گزینه‌های -linkoffline و -link
از گزینهٔ -link در موارد زیر استفاده کنید:
• هنگامی که از مسیر نسبی به سند API خارجی استفاده می‌کنید.
• هنگامی که از نشانی URL مطلق به سند API خارجی استفاده می‌کنید در صورتی
که پوستهٔ (shell) شما اجازهٔ باز کردن اتصال به آن URL را برای خواندن
فراهم سازد..PP هنگامی که از یک URL مطلق برای سند API خارجی استفاده
می‌کنید، اگر شل شما به برنامه‌ای اجازه باز کردن اتصال به آن URL برای
خواندن را نمی‌دهد، از گزینه -linkoffline استفاده کنید. این حالت
می‌تواند زمانی رخ دهد که پشت یک فایروال قرار دارید و سندی که می‌خواهید
به آن پیوند دهید در سمت دیگر آن است.
مثال ۱: پیوند مطلق به اسناد خارجی
اگر می‌خواهید به بسته‌های java.lang، java.io و سایر بسته‌های پلتفرم Java
که در http://docs.oracle.com/javase/8/docs/api/index.html نشان داده
شده‌اند پیوند برقرار کنید، از دستور زیر استفاده کنید:
javadoc -link http://docs.oracle.com/javase/8/docs/api com.mypackage
این دستور مستندات را برای بسته com.mypackage همراه با پیوندهایی به
بسته‌های Java SE تولید می‌کند. مستندات تولیدشده به عنوان مثال در درخت
کلاس‌ها (trees)، شامل پیوندهایی به کلاس Object خواهد بود. سایر گزینه‌ها
مانند گزینه‌های -sourcepath و -d نشان داده نشده‌اند.
مثال ۲: پیوند نسبی به اسناد خارجی
در این مثال، دو بسته با مستنداتی وجود دارند که در اجراهای متفاوتی از
دستور javadoc تولید می‌شوند و این مستندات با یک مسیر نسبی از یکدیگر جدا
شده‌اند. این بسته‌ها عبارتند از com.apipackage (یک API) و com.spipackage
(یک رابط ارائه‌دهنده خدمات یا SPI). شما می‌خواهید مستندات در
docs/api/com/apipackage و docs/spi/com/spipackage قرار گیرند. با فرض
اینکه مستندات بسته API از قبل تولید شده است و docs دایرکتوری جاری است،
با اجرای دستور زیر بسته SPI را با پیوندهایی به مستندات API مستندسازی
می‌کنید: javadoc -d ./spi -link ../api com.spipackage.
توجه داشته باشید که گزینه -link نسبت به دایرکتوری مقصد (docs/spi) نسبی
است.
نکات
گزینه -link به شما امکان می‌دهد به کلاس‌هایی پیوند دهید که در کد شما به
آنها ارجاع داده شده، اما در اجرای فعلی دستور javadoc مستندسازی نشده‌اند.
برای اینکه این پیوندها به صفحات معتبری هدایت شوند، باید بدانید آن صفحات
HTML در کجا قرار دارند و آن مکان را با extdocURL مشخص کنید. این کار به
مستندات شخص ثالث اجازه می‌دهد به مستندات java.* در
http://docs.oracle.com پیوند دهند. هنگامی که می‌خواهید دستور javadoc فقط
به APIهای درون مستنداتی که در اجرای فعلی تولید می‌شوند پیوند ایجاد کند،
گزینه -link را حذف کنید. بدون گزینه -link، دستور javadoc پیوندی به
مستندات ارجاعات خارجی ایجاد نمی‌کند، زیرا نمی‌داند آیا چنین مستنداتی وجود
دارند یا در کجا قرار دارند. گزینه -link می‌تواند در چندین بخش از مستندات
تولیدشده پیوند ایجاد کند؛ بخش Process Source Files را ببینید. کاربرد
دیگر برای پیوندهای متقابل (cross-links) بین مجموعه‌هایی از بسته‌ها است:
دستور javadoc را روی یک مجموعه از بسته‌ها اجرا کنید، سپس دستور javadoc
را دوباره روی مجموعه دیگری از بسته‌ها اجرا نمایید و بدین ترتیب پیوندهای
دوطرفه بین هر دو مجموعه ایجاد کنید.
نحوه ارجاع به یک کلاس
برای اینکه پیوند به یک کلاس ارجاع داده‌شده خارجی ظاهر شود (و نه صرفاً
برچسب متنی آن)، کلاس باید به شیوه زیر ارجاع داده شود. ارجاع به آن در
بدنه یک متد کافی نیست. باید در یک عبارت import یا در یک اعلان
(declaration) به آن ارجاع داده شود. در اینجا مثال‌هایی از نحوه ارجاع به
کلاس java.io.File آمده است:
در هر نوع عبارت import: با استفاده از نویسه عمومی (wildcard import)،
وارد کردن صریح با نام، یا وارد کردن خودکار برای java.lang.*.
در Java SE نسخه 1.3.n و 1.2.n، تنها وارد کردن صریح با نام کار می‌کند.
عبارت import با نویسه عمومی کار نمی‌کند، و همچنین import java.lang.*
خودکار نیز عمل نمی‌کند.
در یک اعلان: void mymethod(File f) {}
این ارجاع می‌تواند در نوع بازگشتی یا نوع پارامتر یک متد، سازنده
(constructor)، فیلد، کلاس یا رابط (interface)، یا در عبارات implements،
extends یا throws باشد.
یک نتیجه مهم این است که هنگام استفاده از گزینه -link، ممکن است پیوندهای
زیادی به دلیل این محدودیت ناخواسته ظاهر نشوند. متن بدون اینکه یک پیوند
باشد نمایش داده خواهد شد. می‌توانید این موارد را از روی هشدارهایی که
صادر می‌کنند شناسایی کنید. ساده‌ترین راه برای ارجاع مناسب به یک کلاس و
افزودن پیوند، وارد کردن (import) آن کلاس است.
فهرست بسته‌ها (Package List)
گزینه -link مستلزم آن است که فایلی با نام package-list، که توسط دستور
javadoc تولید می‌شود، در URL تعیین‌شده با گزینه -link وجود داشته باشد.
فایل package-list یک فایل متنی ساده است که نام بسته‌های مستندسازی‌شده در
آن مکان را فهرست می‌کند. در مثال قبلی، دستور javadoc به دنبال فایلی به
نام package-list در URL مشخص‌شده می‌گردد، نام بسته‌ها را می‌خواند و به آن
بسته‌ها در آن URL پیوند می‌دهد.
برای مثال، فهرست بسته‌ها برای Java SE API در
http://docs.oracle.com/javase/8/docs/api/package-list قرار دارد.
فهرست بسته‌ها به صورت زیر آغاز می‌شود:
java.applet
java.awt
java.awt.color
java.awt.datatransfer
java.awt.dnd
java.awt.event
java.awt.font
and so on ....
هنگامی که javadoc بدون گزینه -link اجرا می‌شود و به نامی برمی‌خورد که
متعلق به یک کلاس ارجاع داده‌شده خارجی است، نام را بدون هیچ پیوندی چاپ
می‌کند. با این حال، هنگامی که گزینه -link استفاده می‌شود، دستور javadoc
فایل package-list را در مکان مشخص‌شده توسط extdocURL برای یافتن نام آن
بسته جستجو می‌کند. هنگامی که نام بسته را پیدا کرد، extdocURL را به عنوان
پیشوند به نام اضافه می‌کند.
برای اینکه هیچ پیوند شکسته‌ای وجود نداشته باشد، تمام مستندات مربوط به
ارجاعات خارجی باید در URLهای مشخص‌شده موجود باشند. دستور javadoc وجود
این صفحات را بررسی نمی‌کند، بلکه تنها وجود package-list را بررسی
می‌نماید.
پیوندهای چندگانه
می‌توانید چندین گزینه -link را برای پیوند به هر تعداد سند تولیدشده خارجی
ارائه دهید. در Javadoc 1.2 یک باگ شناخته‌شده وجود دارد که مانع از ارائه
بیش از یک گزینه -link می‌شود. این مشکل در Javadoc 1.2.2 برطرف شد. برای
هر سند خارجی که می‌خواهید به آن پیوند دهید یک گزینه پیوند جداگانه مشخص
کنید: javadoc -link extdocURL1 -link extdocURL2 ... -link extdocURLn
com.mypackage که در آن extdocURL1، extdocURL2، ... extdocURLn به ترتیب
به ریشه اسناد خارجی اشاره دارند که هر کدام حاوی فایلی به نام package-
list هستند.
پیوندهای متقابل (Cross Links)
توجه داشته باشید هنگام پیوند متقابل بین دو یا چند سند که قبلاً تولید
شده‌اند، ممکن است خودراه‌اندازی (bootstrapping) لازم باشد. اگر هنگام
اجرای دستور javadoc بر روی سند اول، package-list برای هیچ‌یک از اسناد
وجود نداشته باشد، در نتیجه package-list هنوز برای سند دوم نیز وجود
ندارد. بنابراین، برای ایجاد پیوندهای خارجی، باید پس از تولید سند دوم،
سند اول را مجدداً تولید کنید.
در این حالت، هدف از تولید اولیه یک سند، ایجاد فایل package-list آن است
(یا در صورت اطمینان از نام بسته‌ها می‌توانید آن را دستی بسازید). سپس، سند
دوم را به همراه پیوندهای خارجی آن تولید کنید. دستور javadoc در صورتی که
فایل خارجی package-list مورد نیاز وجود نداشته باشد، یک هشدار چاپ می‌کند.
-linkoffline extdocURL packagelistLoc
این گزینه گونه‌ای از گزینه -link است. هر دوی آنها پیوندهایی به
مستندات تولیدشده توسط Javadoc برای کلاس‌های ارجاع داده‌شده خارجی
ایجاد می‌کنند. هنگامی که دستور javadoc نمی‌تواند از طریق اتصال وب
به سندی دسترسی پیدا کند، برای پیوند به آن سند در وب از گزینه
-linkoffline استفاده کنید. زمانی از گزینه -linkoffline استفاده
کنید که فایل package-list سند خارجی در مکان extdocURL قابل
دسترسی نبوده یا وجود ندارد، اما در مکان متفاوتی که با
packageListLoc مشخص می‌شود (معمولاً محلی) وجود دارد. اگر extdocURL
فقط در وب جهانی قابل دسترسی است، گزینه -linkoffline این محدودیت
را که دستور javadoc برای تولید مستندات الزاماً باید اتصال وب
داشته باشد برطرف می‌کند. کاربرد دیگر به عنوان یک راهکار برای
به‌روزرسانی اسناد است: پس از اجرای دستور javadoc روی یک مجموعه
کامل از بسته‌ها، می‌توانید دستور javadoc را دوباره روی مجموعه
کوچکتری از بسته‌های تغییریافته اجرا کنید، تا فایلهای
به‌روزرسانی‌شده بتوانند مجدداً درون مجموعه اصلی جای‌گذاری شوند. در
ادامه مثال‌هایی ارائه شده است. گزینه -linkoffline دو آرگومان
می‌گیرد: اولی رشته‌ای است که باید در پیوندهای <a href> تعبیه شود،
و دومی به گزینه -linkoffline اعلام می‌کند فایل package-list را در
کجا پیدا کند:
• مقدار extdocURL نشانی URL مطلق یا نسبی دایرکتوری‌ای است که حاوی
مستندات خارجی تولیدشده با Javadoc است که می‌خواهید به آن پیوند
دهید. در صورت نسبی بودن، این مقدار باید مسیر نسبی از دایرکتوری
مقصد (مشخص‌شده با گزینه -d) به ریشه بسته‌های در حال پیوند باشد.
برای اطلاعات بیشتر، extdocURL را در گزینه -link ببینید.
• مقدار packagelistLoc مسیر یا URL به دایرکتوری‌ای است که شامل
فایل package-list برای مستندات خارجی است. این مقدار می‌تواند یک
URL (مانند :http یا :file) یا مسیر فایل، و به صورت مطلق یا
نسبی باشد. در صورت نسبی بودن، آن را نسبت به دایرکتوری جاری که
دستور javadoc از آنجا اجرا شده مشخص کنید. نام فایل package-
list را درج نکنید.
می‌توانید چندین گزینه -linkoffline را در یک اجرای معین دستور
javadoc مشخص کنید. پیش از Javadoc 1.2.2، گزینه‌های -linkfile
تنها یک‌بار قابل تعیین بودند.
پیوندهای مطلق به اسناد خارجی
ممکن است در شرایطی باشید که بخواهید به بسته‌های java.lang، java.io و
سایر بسته‌های Java SE در
http://docs.oracle.com/javase/8/docs/api/index.html پیوند دهید.
با این حال، شل شما به وب دسترسی ندارد. در این حالت، مراحل زیر را انجام
دهید:
1. فایل package-list را در یک مرورگر در آدرس
http://docs.oracle.com/javase/8/docs/api/package-list باز کنید.
2. فایل را در یک دایرکتوری محلی ذخیره کرده و با آرگومان دوم،
packagelistLoc، به این نسخه محلی اشاره کنید. در این مثال، فایل
فهرست بسته‌ها در دایرکتوری جاری (.) ذخیره شده است.
دستور زیر مستندات را برای بسته com.mypackage همراه با پیوندهایی به
بسته‌های Java SE تولید می‌کند. مستندات تولیدشده به عنوان مثال در درخت
کلاس‌ها (trees)، شامل پیوندهایی به کلاس Object خواهد بود. سایر گزینه‌های
ضروری مانند -sourcepath نشان داده نشده‌اند.
javadoc -linkoffline http://docs.oracle.com/javase/8/docs/api . com.mypackage
پیوندهای نسبی به اسناد خارجی
استفاده از -linkoffline با مسیرهای نسبی چندان رایج نیست، به این دلیل
ساده که گزینه -link معمولاً کافی است. هنگامی که از گزینه -linkoffline
استفاده می‌کنید، فایل package-list معمولاً محلی است، و هنگامی که از
پیوندهای نسبی استفاده می‌کنید، فایلی که به آن پیوند می‌دهید نیز محلی است؛
بنابراین معمولاً نیازی به ارائه مسیر متفاوت برای دو آرگومان گزینه
-linkoffline وجود ندارد. هنگامی که هر دو آرگومان یکسان باشند، می‌توانید
از گزینه -link استفاده کنید.
ایجاد دستی فایل package-list
اگر فایل package-list هنوز وجود ندارد، اما می‌دانید سند شما به چه نام
بسته‌هایی پیوند خواهد خورد، می‌توانید به صورت دستی نسخه خود را از این
فایل ایجاد کنید و مسیر آن را با packagelistLoc مشخص نمایید. یک مثال
می‌تواند همان مورد قبلی باشد که در آن هنگام تولید اولیه com.apipackage،
فهرست بسته‌ها برای com.spipackage وجود نداشت. این روش زمانی مفید است که
نیاز به تولید مستنداتی دارید که به مستندات خارجی جدیدی پیوند دارند که
نام بسته‌های آنها را می‌دانید، اما هنوز منتشر نشده‌اند. همچنین این روشی
برای ایجاد فایلهای package-list برای بسته‌های تولیدشده با Javadoc 1.0 یا
1.1 است که در آنها فایل package-list تولید نمی‌شد. به همین ترتیب، دو
شرکت می‌توانند فایلهای package-list منتشرنشده خود را به اشتراک بگذارند
تا بتوانند مستندات با پیوند متقابل خود را به طور همزمان عرضه کنند.
پیوند به چندین سند
می‌توانید به ازای هر سند تولیدشده‌ای که می‌خواهید به آن ارجاع دهید، یک‌بار
گزینه -linkoffline را مشخص کنید:
javadoc -linkoffline extdocURL1 packagelistLoc1 -linkoffline extdocURL2
packagelistLoc2 ...
به‌روزرسانی اسناد
همچنین می‌توانید زمانی که پروژه‌تان ده‌ها یا صدها بسته دارد، از گزینه
-linkoffline استفاده کنید. اگر پیش‌تر دستور javadoc را روی کل درخت کد
مبدأ اجرا کرده‌اید، می‌توانید به سرعت تغییرات کوچکی در کامنت‌های مستندسازی
(documentation comments) اعمال کرده و دستور javadoc را روی بخشی از درخت
کد مبدأ دوباره اجرا کنید. توجه داشته باشید که اجرای دوم تنها زمانی به
درستی کار می‌کند که تغییرات شما صرفاً در کامنت‌های مستندسازی باشد و نه در
اعلان‌ها. اگر هرگونه اعلانی را به کد مبدأ اضافه یا حذف کنید یا تغییر
دهید، ممکن است پیوندهای شکسته در نمایه (index)، درخت بسته (package
tree)، فهرست‌های اعضای موروثی، صفحه Use و جاهای دیگر ظاهر شوند.
ابتدا یک دایرکتوری مقصد جدید، مانند update، برای این اجرای کوچک جدید
ایجاد کنید. در این مثال، نام دایرکتوری مقصد اصلی html است. در ساده‌ترین
مثال، به دایرکتوری والد html بروید. آرگومان اول گزینه -linkoffline را
روی دایرکتوری جاری (.) تنظیم کرده و آرگومان دوم را روی مسیر نسبی به
html، جایی که می‌تواند package-list را بیابد، تنظیم نمایید و تنها نام
بسته‌هایی را که می‌خواهید به‌روزرسانی شوند وارد کنید:
javadoc -d update -linkoffline . html com.mypackage
پس از اتمام دستور javadoc، این صفحات کلاس تولیدشده در
update/com/package را (نه نمای کلی overview یا نمایه index) روی فایلهای
اصلی در html/com/package کپی کنید.
-linksource
یک نسخه HTML از هر فایل مبدأ (همراه با شماره خطوط) ایجاد کرده و
پیوندهایی از مستندات HTML استاندارد به آنها اضافه می‌کند. پیوندها
برای کلاس‌ها، رابط‌ها، سازنده‌ها، متدها و فیلدهایی که اعلان آنها در
یک فایل مبدأ است ایجاد می‌شوند. در غیر این صورت، پیوندی ایجاد
نمی‌شود؛ مانند سازنده‌های پیش‌فرض و کلاس‌های تولیدشده.
این گزینه تمام جزئیات پیاده‌سازی خصوصی را در فایلهای مبدأ مشخص‌شده
آشکار می‌کند، از جمله کلاس‌های خصوصی، فیلدهای خصوصی و بدنه متدهای
خصوصی، صرف‌نظر از گزینه‌های -public، -package، -protected و
-private. مگر اینکه از گزینه -private نیز استفاده کنید، همه
کلاس‌ها یا رابط‌های خصوصی از طریق پیوندها قابل دسترسی نخواهند بود.
هر پیوند روی نام شناسه در اعلان آن ظاهر می‌شود. به عنوان مثال،
پیوند به کد مبدأ کلاس Button روی کلمه Button خواهد بود:
public class Button extends Component implements Accessible
پیوند به کد مبدأ متد getLabel در کلاس Button روی کلمه getLabel
قرار دارد:
public String getLabel()
-group groupheading packagepattern:packagepattern
بسته‌ها را در صفحه مرور کلی (overview) بر اساس گروه‌هایی که مشخص
می‌کنید دسته‌بندی می‌کند، یک گروه در هر جدول. شما هر گروه را با یک
گزینه -group مجزا مشخص می‌کنید. گروه‌ها به ترتیبی که در خط فرمان
مشخص شده‌اند در صفحه ظاهر می‌شوند. بسته‌ها در داخل یک گروه به ترتیب
الفبا مرتب می‌شوند. برای یک گزینه -group معین، بسته‌های منطبق با
فهرست عبارات packagepattern در جدولی با عنوان groupheading نمایش
داده می‌شوند.
• مقدار groupheading می‌تواند هر متنی باشد و شامل فاصله (white
space) نیز بشود. این متن در سربرگ جدول برای آن گروه قرار داده
می‌شود..TP 0.2i • مقدار packagepattern می‌تواند هر نام بسته‌ای در
ابتدای نام هر بسته‌ای باشد که به دنبال آن یک ستاره (*) آمده
است. ستاره تنها نویسهٔ عام (wildcard) مجاز است و به معنای تطبیق
با هر نویسه‌ای می‌باشد. با جدا کردن الگوها به‌وسیلهٔ دونقطه (:)
می‌توان چند الگو را در یک گروه قرار داد. اگر در یک الگو یا
فهرستی از الگوها از ستاره استفاده می‌کنید، فهرست الگوها باید
داخل علامت نقل‌قول قرار گیرد، مانند "java.lang*:java.util".
هنگامی که گزینهٔ -group را مشخص نکنید، همهٔ بسته‌ها در یک گروه با عنوان
Packages و زیرعنوان‌های مناسب قرار می‌گیرند. اگر زیرعنوان‌ها شامل همهٔ
بسته‌های مستندسازی‌شده نباشند (همهٔ گروه‌ها)، بسته‌های باقی‌مانده در گروهی
جداگانه با زیرعنوان Other Packages ظاهر می‌شوند.
به عنوان مثال، دستور javadoc زیر بسته‌های مستندسازی‌شده را به سه دستهٔ
Core، Extension و Other Packages تفکیک می‌کند. نقطهٔ انتهایی (.) در
java.lang* ظاهر نمی‌شود. گنجاندن نقطه، مانند java.lang.*، بستهٔ java.lang
را حذف می‌کند.
javadoc -group "Core Packages" "java.lang*:java.util"
-group "Extension Packages" "javax.*"
java.lang java.lang.reflect java.util javax.servlet java.new
Core Packages
java.lang
java.lang.reflect
java.util
Extension Packages
javax.servlet
Other Packages
java.new
-nodeprecated
از تولید هرگونه API منسوخ‌شده (deprecated) در مستندات جلوگیری
می‌کند. این گزینه کاری را انجام می‌دهد که گزینهٔ -nodeprecatedlist
انجام می‌دهد، بعلاوه در بقیهٔ بخش‌های مستندات نیز هیچ API
منسوخ‌شده‌ای تولید نمی‌کند. این ویژگی هنگام نوشتن کد، زمانی که
نمی‌خواهید تمرکزتان توسط کدهای منسوخ‌شده برهم بخورد، مفید است.
-nodeprecatedlist
از تولید فایلی که شامل فهرست APIهای منسوخ‌شده است (deprecated-
list.html) و پیوند موجود در نوار ناوبری به آن صفحه جلوگیری
می‌کند. دستور javadoc همچنان به تولید APIهای منسوخ‌شده در سرتاسر
سایر بخش‌های سند ادامه می‌دهد. این ویژگی زمانی مفید است که کد مبدأ
شما فاقد هرگونه API منسوخ‌شده باشد و بخواهید نوار ناوبری خلوت‌تری
داشته باشید.
-nosince
بخش‌های Since مربوط به برچسب‌های @since را از اسناد تولیدشده حذف
می‌کند.
-notree
صفحات سلسله‌مراتب کلاس/رابط را از اسناد تولیدشده حذف می‌کند. این‌ها
صفحاتی هستند که با استفاده از دکمهٔ Tree در نوار ناوبری به آنها
دسترسی پیدا می‌کنید. این سلسله‌مراتب به‌طور پیش‌فرض تولید می‌شود.
-noindex
نمایه (index) را از اسناد تولیدشده حذف می‌کند. نمایه به‌طور پیش‌فرض
تولید می‌شود.
-nohelp
پیوند HELP را از نوارهای ناوبری در بالا و پایین هر صفحه از خروجی
حذف می‌کند.
-nonavbar
از تولید نوار ناوبری، سربرگ و پابرگ که معمولاً در بالا و پایین
صفحات تولیدشده وجود دارند، جلوگیری می‌کند. گزینهٔ -nonavbar هیچ
تأثیری بر گزینهٔ -bottom ندارد. گزینهٔ -nonavbar زمانی مفید است که
فقط به محتوا علاقه دارید و نیازی به ناوبری ندارید، مانند زمانی
که فایلها را صرفاً برای چاپ به PostScript یا PDF تبدیل می‌کنید.
-helpfile path\filename
مسیر یک فایل راهنمای جایگزین path\filename را مشخص می‌کند که
پیوند HELP در نوارهای ناوبری بالا و پایین به آن ارجاع می‌دهد.
بدون این گزینه، دستور javadoc یک فایل راهنمای help-doc.html
ایجاد می‌کند که مسیر آن در خودِ دستور javadoc کدگذاری ثابت شده
است. این گزینه به شما امکان می‌دهد رفتار پیش‌فرض را بازنویسی کنید.
نام فایل می‌تواند هر نامی باشد و محدود به help-doc.html نیست.
دستور javadoc پیوندهای نوار ناوبری را بر همان اساس تنظیم می‌کند،
برای مثال:
javadoc -helpfile /home/user/myhelp.html java.awt.
-stylesheet path/filename
مسیر یک فایل شیوه‌نامهٔ (stylesheet) جایگزین HTML را مشخص می‌کند.
بدون این گزینه، دستور javadoc به‌طور خودکار یک فایل شیوه‌نامه به
نام stylesheet.css ایجاد می‌کند که درون دستور javadoc به صورت
کدگذاری ثابت تعبیه شده است. این گزینه امکان بازنویسی مقدار
پیش‌فرض را فراهم می‌کند. نام فایل می‌تواند هر نامی باشد و محدود به
stylesheet.css نیست، برای مثال:
javadoc -stylesheet file /home/user/mystylesheet.css com.mypackage
-serialwarn
هشدارهای زمان ترجمه (کامپایل) را برای برچسب‌های گم‌شدهٔ @serial
تولید می‌کند. به‌طور پیش‌فرض، Javadoc 1.2.2 و نسخه‌های پس از آن هیچ
هشدار سریالی‌سازی تولید نمی‌کنند. این رفتار در مقایسه با نسخه‌های
پیشین معکوس شده است. از این گزینه برای نمایش هشدارهای سریالی‌سازی
استفاده کنید، که به مستندسازی مناسب فیلدهای سریالی‌پذیر پیش‌فرض و
متدهای writeExternal کمک می‌کند.
-charset name
مجموعه‌نویسهٔ (character set) زبان HTML را برای این سند مشخص
می‌کند. نام باید یک نام ترجیحی MIME باشد، همان‌طور که در ثبت‌نامهٔ
IANA، مجموعه‌نویسه‌ها در
http://www.iana.org/assignments/character-sets مشخص شده است.
برای مثال، javadoc -charset "iso-8859-1" mypackage خط زیر را در
بخش head هر صفحهٔ تولیدشده درج می‌کند:
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
این برچسب META در استاندارد HTML (۴۱۹۷۲۶۵ و ۴۱۳۷۳۲۱)، HTML
Document Representation، در آدرس http://www.w3.org/TR/REC-
html40/charset.html#h-5.2.2 شرح داده شده است.
همچنین گزینه‌های -encoding و -docencoding name را ببینید.
-docencoding name
کدگذاری (encoding) فایلهای HTML تولیدشده را مشخص می‌کند. نام باید
یک نام ترجیحی MIME باشد، همان‌طور که در ثبت‌نامهٔ IANA،
مجموعه‌نویسه‌ها در http://www.iana.org/assignments/character-sets
مشخص شده است.
اگر گزینهٔ -docencoding را نادیده بگیرید اما از گزینهٔ -encoding
استفاده کنید، کدگذاری فایلهای HTML تولیدشده توسط گزینهٔ -encoding
تعیین می‌شود، برای مثال: javadoc -docencoding "iso-8859-1"
mypackage. همچنین گزینه‌های -encoding و -docencoding name را
ببینید.
-keywords
برچسب‌های کلیدواژهٔ <META> در HTML را به فایل تولیدشده برای هر
کلاس اضافه می‌کند. این برچسب‌ها می‌توانند به موتورهای جستجویی که به
دنبال برچسب‌های <META> می‌گردند در یافتن صفحات کمک کنند. بیشتر
موتورهای جستجویی که کل اینترنت را جستجو می‌کنند، به برچسب‌های
<META> توجهی نمی‌کنند، زیرا صفحات ممکن است از آنها سوءاستفاده
کنند. موتورهای جستجوی ارائه‌شده توسط شرکت‌هایی که جستجوی خود را به
وب‌سایت خودشان محدود می‌کنند، می‌توانند با بررسی برچسب‌های <META>
بهره‌مند شوند. برچسب‌های <META> شامل نام کامل واجد شرایط (fully
qualified) کلاس و نام‌های غیرواجد شرایط فیلدها و متدها هستند.
سازنده‌ها (constructors) گنجانده نمی‌شوند زیرا با نام کلاس یکسان
هستند. برای مثال، کلاس String با این کلیدواژه‌ها آغاز می‌شود:
<META NAME="keywords" CONTENT="java.lang.String class">
<META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">
<META NAME="keywords" CONTENT="length()">
<META NAME="keywords" CONTENT="charAt()">
-tag tagname:Xaoptcmf:"taghead"
دستور javadoc را قادر می‌سازد تا یک برچسب بلوکی سفارشی ساده و
تک‌آرگومانی @tagname را در یادداشت‌های مستندسازی تفسیر کند. برای
اینکه دستور javadoc بتواند املای نام برچسب‌ها را بررسی کند، مهم
است که برای هر برچسب سفارشی موجود در کد مبدأ یک گزینهٔ -tag درج
کنید و آن‌هایی را که در اجرای فعلی خروجی داده نمی‌شوند غیرفعال
کنید (با X). دونقطه (:) همواره به عنوان جداکننده عمل می‌کند.
گزینهٔ -tag سربرگ برچسب taghead را به صورت برجسته (bold) خروجی
می‌دهد که در خط بعدی متنِ تک‌آرگومان آن قرار می‌گیرد. مانند هر برچسب
بلوکی دیگر، متن آرگومان می‌تواند حاوی برچسب‌های درون‌خطی باشد که
آنها نیز تفسیر می‌شوند. خروجی شبیه به برچسب‌های استاندارد
تک‌آرگومانی، مانند برچسب‌های @return و @author است. حذف مقداری
برای taghead باعث می‌شود tagname به عنوان سربرگ قرار گیرد.
جای‌گذاری برچسب‌ها: آرگومان‌های Xaoptcmf مشخص می‌کنند که برچسب در
کجای کد مبدأ مجاز به قرارگیری است و آیا می‌توان برچسب را غیرفعال
کرد (با استفاده از X) یا خیر. می‌توانید a را برای مجاز کردن برچسب
در همهٔ مکان‌ها، یا هر ترکیبی از حروف دیگر را مشخص کنید:
X (غیرفعال کردن برچسب)
a (همه)
o (نمای کلی)
p (بسته‌ها)
t (نوع‌ها، یعنی کلاس‌ها و رابط‌ها)
c (سازنده‌ها)
m (متدها)
f (فیلدها)
نمونه‌هایی از برچسب‌های منفرد: نمونه‌ای از یک گزینهٔ برچسب برای
برچسبی که می‌تواند در هر کجای کد مبدأ استفاده شود عبارت است از:
-tag todo:a:"To Do:".
اگر می‌خواهید برچسب @todo فقط با سازنده‌ها، متدها و فیلدها استفاده
شود، از این عبارت استفاده می‌کنید: -tag todo:cmf:"To Do:".
توجه داشته باشید که آخرین دونقطه (:) یک جداکنندهٔ پارامتر نیست،
بلکه بخشی از متن سربرگ است. شما می‌توانید از هر یک از این
گزینه‌های برچسب برای کدهای مبدئی که حاوی برچسب @todo هستند
استفاده کنید، مانند: @todo The documentation for this method
needs work.
علامت دونقطه در نام برچسب‌ها: برای گریز از دونقطه‌ای (escape) که
می‌خواهید در نام یک برچسب استفاده کنید، از یک بک‌اسلش استفاده
نمایید. از گزینهٔ -tag ejb\\:bean:a:"EJB Bean:" برای یادداشت
مستندسازی زیر استفاده کنید:
/**
* @ejb:bean
*/
بررسی املای نام برچسب‌ها: برخی از توسعه‌دهندگان برچسب‌های سفارشی را
در کد مبدأ قرار می‌دهند که همیشه مایل به چاپ آنها در خروجی
نیستند. در این موارد، مهم است که تمام برچسب‌های موجود در کد مبدأ
را فهرست کنید، برچسب‌هایی را که می‌خواهید در خروجی ظاهر شوند فعال
کرده و آن‌هایی را که نمی‌خواهید غیرفعال نمایید. وجود X برچسب را
غیرفعال می‌کند، در حالی که عدم وجود آن برچسب را فعال می‌سازد. این
کار اطلاعات کافی را در اختیار دستور javadoc قرار می‌دهد تا بداند
آیا برچسبی که با آن مواجه شده ناشناخته است (که احتمالاً نتیجهٔ یک
خطای تایپی یا املای نادرست است) یا خیر. دستور javadoc در این
موارد یک هشدار چاپ می‌کند. می‌توانید X را به مقادیر جای‌گذاری که از
قبل موجودند اضافه کنید، به طوری که هر زمان خواستید برچسب را فعال
کنید، به سادگی X را حذف نمایید. برای مثال، اگر برچسب @todo
برچسبی است که می‌خواهید از خروجی حذف شود، می‌توانید از این عبارت
استفاده کنید: -tag todo:Xcmf:"To Do:". اگر ترجیح می‌دهید آن را
ساده نگه دارید، از این دستور استفاده کنید: -tag todo:X. نحو -tag
todo:X حتی زمانی که برچسب @todo توسط یک taglet تعریف شده باشد
نیز کار می‌کند.
ترتیب برچسب‌ها: ترتیب گزینه‌های -tag و -taglet ترتیب خروجی برچسب‌ها
را تعیین می‌کند. می‌توانید برچسب‌های سفارشی را با برچسب‌های
استاندارد ترکیب کنید تا در میان آنها پراکنده شوند. گزینه‌های
برچسب برای برچسب‌های استاندارد صرفاً جای‌نگه‌دار (placeholder) برای
تعیین ترتیب هستند. آنها فقط نام برچسب استاندارد را می‌پذیرند.
زیرعنوان‌های برچسب‌های استاندارد قابل تغییر نیستند. این موضوع در
مثال زیر نشان داده شده است. اگر گزینهٔ -tag موجود نباشد، موقعیت
گزینهٔ -taglet ترتیب آن را مشخص می‌کند. اگر هر دو حضور داشته
باشند، هر کدام که در خط فرمان در جایگاه آخر قرار گیرد ترتیب را
مشخص می‌کند. این به این دلیل است که برچسب‌ها و tagletها به ترتیبی
که در خط فرمان ظاهر می‌شوند پردازش می‌گردند. برای مثال، اگر
گزینه‌های -taglet و -tag دارای مقدار نام todo باشند، آن گزینه‌ای
که در آخر خط فرمان قرار دارد ترتیب را مشخص می‌کند.
نمونه‌ای از یک مجموعهٔ کامل برچسب‌ها: این مثال عبارت To Do را بعد
از Parameters و قبل از Throws در خروجی درج می‌کند. با استفاده از
X، همچنین مشخص می‌کند که ممکن است با برچسب @example در کد مبدأ
مواجه شود که نباید در این اجرا خروجی داده شود. اگر از برچسب
@argfile استفاده کنید، می‌توانید برچسب‌ها را در خطوط جداگانه در یک
فایل آرگومان مشابه این قرار دهید (نیازی به نویسه‌های ادامه‌دهندهٔ
خط نیست):
-tag param
-tag return
-tag todo:a:"To Do:"
-tag throws
-tag see
-tag example:X
هنگامی که دستور javadoc یادداشت‌های مستندسازی را تجزیه می‌کند، هر
برچسبی که با آن مواجه شود و نه برچسب استاندارد باشد و نه از طریق
گزینه‌های -tag یا -taglet ارسال شده باشد، ناشناخته تلقی شده و یک
هشدار صادر می‌شود.
برچسب‌های استاندارد ابتدا در یک فهرست داخلی با ترتیب پیش‌فرض خود
ذخیره می‌شوند. هر زمان که گزینه‌های -tag استفاده شوند، آن برچسب‌ها
به انتهای این فهرست اضافه می‌شوند. برچسب‌های استاندارد از موقعیت
پیش‌فرض خود جابه‌جا می‌شوند. بنابراین، اگر گزینهٔ -tag برای یک برچسب
استاندارد نادیده گرفته شود، آن برچسب در موقعیت پیش‌فرض خود باقی
می‌ماند.
جلوگیری از تداخل: اگر می‌خواهید فضای نام (namespace) اختصاصی خود
را بسازید، می‌توانید از شیوهٔ نام‌گذاریِ تفکیک‌شده با نقطه، مشابه
آنچه برای بسته‌ها به کار می‌رود، استفاده کنید: com.mycompany.todo.
شرکت Oracle به ایجاد برچسب‌های استانداردی که نام آنها حاوی نقطه
نیست ادامه خواهد داد. هر برچسبی که ایجاد کنید رفتار برچسبی با
همان نام را که توسط Oracle تعریف شده است لغو (override) می‌کند.
اگر یک برچسب یا taglet به نام @todo بسازید، حتی در صورتی که بعداً
Oracle برچسب استانداردی با همین نام بسازد، همواره همان رفتاری را
خواهد داشت که شما تعریف کرده‌اید.
حاشیه‌نویسی‌ها در برابر برچسب‌های Javadoc: به‌طور کلی، اگر
نشانه‌گذاری مورد نظری که می‌خواهید اضافه کنید قرار است بر مستندات
تأثیر بگذارد یا آن را تولید کند، باید یک برچسب Javadoc باشد. در
غیر این صورت، باید یک حاشیه‌نویسی (annotation) باشد. به بخش
Custom Tags and Annotations در How to Write Doc Comments for the
Javadoc Tool در آدرس
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#annotations
مراجعه کنید.
همچنین می‌توانید با گزینهٔ -taglet برچسب‌های بلوکی پیچیده‌تر یا
برچسب‌های درون‌خطی سفارشی ایجاد کنید..TP -taglet class
فایل کلاسی را مشخص می‌کند که تگ‌لت (taglet) مورد استفاده در تولید
مستندات برای آن تگ را آغاز می‌نماید. برای مقدار class از نام کامل
و واجد شرایط (fully qualified name) استفاده کنید. این تگ‌لت
همچنین تعداد آرگومان‌های متنی را که تگ سفارشی دارد مشخص می‌کند.
تگ‌لت این آرگومان‌ها را می‌پذیرد، آنها را پردازش می‌کند و خروجی را
تولید می‌نماید. برای مستندات جامع به همراه نمونه‌های تگ‌لت، به بخش
Taglet Overview در نشانی
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/taglet/overview.html
مراجعه کنید.
تگ‌لت‌ها برای تگ‌های بلوکی یا درون‌خطی (inline) مفید هستند. آنها
می‌توانند هر تعداد آرگومان داشته باشند و رفتارهای سفارشی را
پیاده‌سازی کنند، مانند پررنگ (bold) کردن متن، قالب‌بندی بالت‌ها،
نوشتن متن در یک فایل، یا آغاز فرایندهای دیگر. تگ‌لت‌ها تنها
می‌توانند تعیین کنند که یک تگ کجا و با چه قالبی ظاهر شود. تمام
تصمیمات دیگر توسط doclet گرفته می‌شود. یک تگ‌لت نمی‌تواند کارهایی
مانند حذف یک نام کلاس از فهرست کلاس‌های گنجانده‌شده را انجام دهد.
با این حال، می‌تواند اثرات جانبی (side effects) را اجرا کند،
مانند چاپ متن تگ در یک فایل یا راه‌اندازی فرایندی دیگر. از گزینهٔ
-tagletpath برای مشخص کردن مسیر تگ‌لت استفاده کنید. مثال زیر تگ‌لت
To Do را بعد از Parameters و قبل از Throws در صفحات تولیدشده درج
می‌کند. به عنوان روش جایگزین، می‌توانید از گزینهٔ -taglet به جای
گزینهٔ -tag آن استفاده کنید، اما خواندن آن ممکن است دشوار باشد.
-taglet com.sun.tools.doclets.ToDoTaglet
-tagletpath /home/taglets
-tag return
-tag param
-tag todo
-tag throws
-tag see
-tagletpath tagletpathlist
مسیرهای جستجو را برای یافتن فایلهای کلاس تگ‌لت مشخص می‌کند. مقدار
tagletpathlist می‌تواند شامل چند مسیر باشد که با دونقطه (:) از
یکدیگر جدا شده‌اند. دستور javadoc تمام زیردایرکتوری‌های مسیرهای
مشخص‌شده را جستجو می‌کند.
-docfilesubdirs
رونوشت‌برداری عمیق (deep copying) از دایرکتوری‌های doc-files را
فعال می‌کند. زیردایرکتوری‌ها و تمامی محتویات به‌صورت بازگشتی در
مقصد کپی می‌شوند. برای مثال، دایرکتوری doc-files/example/images و
تمام محتویات آن کپی خواهند شد. همچنین گزینه‌ای برای استثنا کردن
زیردایرکتوری‌ها وجود دارد.
-excludedocfilessubdir name1:name2
هر یک از زیردایرکتوری‌های doc-files با نام‌های مشخص‌شده را استثنا
می‌کند. این کار از کپی شدن زیردایرکتوری‌های SCCS و سایر
دایرکتوری‌های سیستم کنترل کد منبع جلوگیری می‌کند.
-noqualifier all | packagename1:packagename2...
نام‌های توصیف‌کنندهٔ بسته (qualifying package names) را از نام
کلاس‌ها در خروجی حذف می‌کند. آرگومان گزینهٔ -noqualifier یا all است
(همهٔ توصیف‌کننده‌های بسته حذف می‌شوند) یا فهرستی از بسته‌ها که با
دونقطه از هم جدا شده‌اند، به همراه کاراکترهای عمومی (wildcards)،
که باید به عنوان توصیف‌کننده حذف شوند. نام بسته از جاهایی که نام
کلاس یا واسط ظاهر می‌شود حذف می‌گردد. بخش Process Source Files را
ببینید.
مثال زیر تمام توصیف‌کننده‌های بسته را حذف می‌کند: -noqualifier all.
مثال زیر توصیف‌کننده‌های بستهٔ java.lang و java.io را حذف می‌کند:
-noqualifier java.lang:java.io.
مثال زیر توصیف‌کننده‌های بسته‌ای را که با java شروع می‌شوند و
زیربسته‌های com.sun را حذف می‌کند، اما javax را حذف نمی‌کند:
-noqualifier java.*:com.sun.*.
در جاهایی که یک توصیف‌کنندهٔ بسته طبق رفتار پیشین ظاهر می‌شد، نام
می‌تواند به شکل مناسب کوتاه شود. بخش How a Name Appears را
ببینید. این قاعده چه از گزینهٔ -noqualifier استفاده شود و چه نشود
اعمال می‌گردد.
-notimestamp
برچسب زمانی (time stamp) را که در یک کامنت HTML در بالای هر صفحه
از HTMLهای تولیدشده پنهان است، غیرفعال می‌کند. گزینهٔ -notimestamp
زمانی مفید است که می‌خواهید دستور javadoc را روی دو پایگاه کد
منبع اجرا کرده و تفاوت‌های بین آنها را با diff به دست آورید، زیرا
از این که برچسب‌های زمانی باعث ایجاد تفاوت در خروجی diff شوند
جلوگیری می‌کند (که در غیر این صورت در هر صفحه یک diff ایجاد
می‌شد). برچسب زمانی شامل شماره انتشار دستور javadoc است و در حال
حاضر چیزی شبیه به این ظاهر می‌شود: <!-- Generated by javadoc
(build 1.5.0_01) on Thu Apr 02 14:04:52 IST 2009 -->.
-nocomment
کل متن کامنت، شامل توضیحات اصلی و تمام تگ‌ها را نادیده گرفته و
تنها اعلان‌ها (declarations) را تولید می‌کند. این گزینه به شما
اجازه می‌دهد تا از فایلهای منبعی که در ابتدا برای هدف دیگری در
نظر گرفته شده بودند مجدداً استفاده کنید تا بتوانید در مراحل اولیه
یک پروژه جدید، اسکلت مستندات HTML را تولید نمایید.
-sourcetab tablength
تعداد فاصله‌هایی (spaces) را که هر تب در سورس استفاده می‌کند مشخص
می‌نماید.
فایلهای آرگومان خط فرمان (COMMAND-LINE ARGUMENT FILES)
برای کوتاه‌تر یا ساده‌تر کردن دستور javadoc، می‌توانید یک یا چند فایل حاوی
آرگومان‌های دستور javadoc (به جز گزینه‌های -J) را مشخص کنید. این امکان به
شما اجازه می‌دهد تا دستورهای javadoc با هر طولی را در هر سیستم‌عاملی
ایجاد کنید.
یک فایل آرگومان می‌تواند شامل گزینه‌های javac و نام‌های فایل منبع در هر
ترکیبی باشد. آرگومان‌های درون یک فایل می‌توانند با فاصله یا با خط جدید از
یکدیگر جدا شوند. اگر نام فایلی دارای فاصله است، کل نام فایل را داخل
علامت نقل‌قول دوتایی قرار دهید.
نام‌های فایل درون یک فایل آرگومان نسبت به دایرکتوری جاری سنجیده می‌شوند،
نه نسبت به مکان فایل آرگومان. کاراکترهای عمومی (*) در این فهرست‌ها مجاز
نیستند (مانند تعیین *.java). استفاده از علامت @ برای تفسیر بازگشتی
فایلها پشتیبانی نمی‌شود. گزینه‌های -J پشتیبانی نمی‌شوند زیرا به اجراکننده
(launcher) ارسال می‌شوند که از فایلهای آرگومان پشتیبانی نمی‌کند.
هنگام اجرای دستور javadoc، مسیر و نام هر فایل آرگومان را با نویسهٔ پیشین
@ ارسال کنید. زمانی که دستور javadoc با آرگومانی مواجه می‌شود که با
علامت @ آغاز شده است، محتویات آن فایل را در فهرست آرگومان‌ها بسط می‌دهد.
مثال ۱: تک‌فایل آرگومان
می‌توانید از یک فایل آرگومان تکی به نام argfile برای نگهداری تمام
آرگومان‌های دستور javadoc استفاده کنید: javadoc @argfile. فایل آرگومان
شامل محتویات هر دو فایل است، همان‌طور که در مثال بعدی نشان داده شده است.
مثال ۲: دو فایل آرگومان
می‌توانید دو فایل آرگومان ایجاد کنید: یکی برای گزینه‌های دستور javadoc و
دیگری برای نام‌های بسته‌ها یا نام‌های فایلهای منبع. توجه داشته باشید که
فهرست‌های زیر فاقد نویسه‌های ادامه‌دهندهٔ خط هستند.
فایلی به نام options ایجاد کنید که شامل موارد زیر باشد:
-d docs-filelist
-use
-splitindex
-windowtitle 'Java SE 7 API Specification'
-doctitle 'Java SE 7 API Specification'
-header '<b>Java™ SE 7</b>'
-bottom 'Copyright © 1993-2011 Oracle and/or its affiliates. All rights reserved.'
-group "Core Packages" "java.*"
-overview /java/pubs/ws/1.7.0/src/share/classes/overview-core.html
-sourcepath /java/pubs/ws/1.7.0/src/share/classes
فایلی به نام packages ایجاد کنید که شامل موارد زیر باشد:
com.mypackage1
com.mypackage2
com.mypackage3
دستور javadoc را به صورت زیر اجرا کنید:
javadoc @options @packages
مثال ۳: فایلهای آرگومان دارای مسیر
فایلهای آرگومان می‌توانند مسیر داشته باشند، اما هر نام فایلی درون این
فایلها نسبت به دایرکتوری کاری جاری سنجیده می‌شود (نه نسبت به path1 یا
path2):
javadoc @path1/options @path2/packages
مثال ۴: آرگومان‌های گزینه
مثال زیر یک آرگومان مربوط به یکی از گزینه‌های دستور javadoc را در یک
فایل آرگومان ذخیره می‌کند. از گزینهٔ -bottom استفاده شده زیرا می‌تواند
آرگومانی طولانی داشته باشد. می‌توانید فایلی به نام bottom ایجاد کنید تا
حاوی این آرگومان متنی باشد:
<font size="-1">
<a href="http://bugreport.sun.com/bugreport">Submit a bug or feature</a><br/>
Copyright © 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>
دستور javadoc را به صورت زیر اجرا کنید: javadoc -bottom @bottom
@packages.
همچنین می‌توانید گزینهٔ -bottom را در ابتدای فایل آرگومان قرار دهید و
دستور javadoc را به این صورت اجرا کنید: javadoc @bottom @packages..SH
"اجرای دستور JAVADOC (RUNNING THE JAVADOC COMMAND)" شماره نسخهٔ دستور
javadoc را می‌توان با گزینهٔ javadoc -J-version تعیین کرد. شماره نسخهٔ
doclet استاندارد در جریان خروجی ظاهر می‌شود. این خروجی را می‌توان با
گزینهٔ -quiet غیرفعال کرد.
برای فراخوانی دستور javadoc از درون برنامه‌های نوشته‌شده به زبان Java، از
رابط برنامه‌نویسی عمومی (API) استفاده کنید. این رابط در
com.sun.tools.javadoc.Main قرار دارد (و دستور javadoc قابلیت
چندباره‌ورود یا reentrant دارد). برای کسب اطلاعات بیشتر، The Standard
Doclet را در
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/standard-
doclet.html#runningprogrammatically ببینید.
دستورالعمل‌های زیر doclet استاندارد HTML را فراخوانی می‌کنند. برای
فراخوانی یک doclet سفارشی، از گزینه‌های -doclet و -docletpath استفاده
کنید. بخش Doclet Overview را در
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/overview.html
ببینید.
مثال‌های ساده (SIMPLE EXAMPLES)
می‌توانید دستور javadoc را روی تمام بسته‌ها یا روی فایلهای سورس جداگانه
اجرا کنید. هر نام بسته دارای یک نام دایرکتوری متناظر است.
در مثال‌های زیر، فایلهای سورس در /home/src/java/awt/*.java قرار دارند.
دایرکتوری مقصد /home/html است.
مستندسازی یک یا چند بسته
برای مستندسازی یک بسته، فایلهای سورس آن بسته باید در دایرکتوری‌ای قرار
داشته باشند که نامی یکسان با بسته دارد.
اگر نام یک بسته دارای چندین شناسه باشد (که با نقطه جدا شده‌اند، مانند
java.awt.color)، در این صورت هر شناسهٔ بعدی باید با یک زیردایرکتوری
عمیق‌تر متناظر باشد (مانند java/awt/color).
تا زمانی که -sourcepath به هر دو درخت اشاره کند، می‌توانید فایلهای سورس
یک بستهٔ واحد را بین دو درخت دایرکتوری واقع در مکان‌های مختلف تقسیم کنید.
برای مثال، src1/java/awt/color و src2/java/awt/color.
می‌توانید دستور javadoc را یا با تغییر دایرکتوری (با دستور cd) یا با
استفاده از گزینهٔ -sourcepath اجرا کنید. مثال‌های زیر هر دو روش را نشان
می‌دهند.
مثال ۱: اجرای بازگشتی از یک یا چند بسته
این مثال از -sourcepath استفاده می‌کند تا دستور javadoc بتواند از هر
دایرکتوری اجرا شود، و از -subpackages (گزینه‌ای جدید در نسخهٔ 1.4) برای
اجرای بازگشتی بهره می‌برد. این دستور زیربسته‌های دایرکتوری java را پیمایش
می‌کند، به استثنای بسته‌هایی که ریشه در java.net و java.lang دارند. توجه
داشته باشید که این کار java.lang.ref را که زیربسته‌ای از java.lang است
مستثنی می‌کند. برای پیمایش سایر درخت‌های بسته نیز می‌توانید نام آنها را به
آرگومان -subpackages اضافه کنید، مانند java:javax:org.xml.sax.
javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude
مثال ۲: تغییر به دایرکتوری ریشه و اجرای بسته‌های صریح
به دایرکتوری والدِ بستهٔ کاملاً مشخص‌شده (fully qualified) بروید. سپس دستور
javadoc را با نام یک یا چند بسته‌ای که می‌خواهید مستندسازی کنید اجرا
نمایید:
cd /home/src/
javadoc -d /home/html java.awt java.awt.event
برای پیمایش سایر درخت‌های بسته نیز نام آنها را به آرگومان -subpackages
پیوست کنید، مانند java:javax:org.xml.sax.
مثال ۳: اجرا از هر دایرکتوری روی بسته‌های صریح در یک درخت
در این حالت، اهمیتی ندارد که دایرکتوری فعلی چه باشد. دستور javadoc را
اجرا کرده و از گزینهٔ -sourcepath به همراه دایرکتوری والدِ بستهٔ سطح بالا
(top-level) استفاده کنید. نام یک یا چند بسته‌ای را که می‌خواهید مستندسازی
کنید مشخص نمایید:
javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event
مثال ۴: اجرا از هر دایرکتوری روی بسته‌های صریح در چندین درخت
دستور javadoc را اجرا کرده و از گزینهٔ -sourcepath همراه با فهرستی از
مسیرهای ریشهٔ هر درخت که با دونقطه (:) جدا شده‌اند استفاده نمایید. نام یک
یا چند بسته‌ای را که می‌خواهید مستندسازی کنید مشخص کنید. نیازی نیست تمام
فایلهای سورس یک بستهٔ مشخص در یک دایرکتوری ریشهٔ واحد قرار داشته باشند،
اما باید در جایی در طول مسیر سورس (source path) پیدا شوند.
javadoc -d /home/html -sourcepath /home/src1:/home/src2 java.awt java.awt.event
نتیجه این است که تمام حالت‌ها مستنداتی با ساختار HTML برای کلاس‌ها و
رابط‌های public و protected در بسته‌های java.awt و java.awt.event تولید
کرده و فایلهای HTML را در دایرکتوری مقصدِ مشخص‌شده ذخیره می‌کنند. از آنجا
که دو یا چند بسته در حال تولید هستند، سند دارای سه قاب (frame) تحت HTML
خواهد بود: یکی برای فهرست بسته‌ها، دیگری برای فهرست کلاس‌ها، و سومی برای
صفحات اصلی کلاس‌ها.
مستندسازی یک یا چند کلاس
روش دوم برای اجرای دستور javadoc، ارسال یک یا چند فایل سورس است.
می‌توانید javadoc را به یکی از دو روش زیر اجرا کنید: با تغییر دایرکتوری
(با دستور cd) یا با مشخص کردن کامل مسیر فایلهای سورس. مسیرهای نسبی نسبت
به دایرکتوری فعلی سنجیده می‌شوند. هنگام ارسال فایلهای سورس، گزینهٔ
-sourcepath نادیده گرفته می‌شود. برای تعیین گروهی از کلاس‌ها می‌توانید از
نویسه‌های عام خط فرمان، مانند ستاره (*)، استفاده کنید.
مثال ۱: تغییر به دایرکتوری سورس
به دایرکتوری حاوی فایلهای سورس بروید. سپس دستور javadoc را با نام یک یا
چند فایل سورسی که می‌خواهید مستندسازی کنید اجرا نمایید.
این مثال مستنداتی با ساختار HTML برای کلاس‌های Button، Canvas و کلاس‌هایی
که با Graphics آغاز می‌شوند تولید می‌کند. از آنجا که به‌جای نام بسته‌ها،
فایلهای سورس به عنوان آرگومان به دستور javadoc داده شده‌اند، سند دارای
دو قاب خواهد بود: یکی برای فهرست کلاس‌ها و دیگری برای صفحهٔ اصلی.
cd /home/src/java/awt
javadoc -d /home/html Button.java Canvas.java Graphics*.java
مثال ۲: تغییر به دایرکتوری ریشهٔ بسته
این روش برای مستندسازی فایلهای سورس منفرد از زیربسته‌های مختلف که ریشهٔ
یکسانی دارند مفید است. به دایرکتوری ریشهٔ بسته بروید و فایلهای سورس را
همراه با مسیرشان از ریشه مشخص نمایید.
cd /home/src/
javadoc -d /home/html java/awt/Button.java java/applet/Applet.java
مثال ۳: مستندسازی فایلها از هر دایرکتوری
در این حالت، اهمیتی ندارد که دایرکتوری فعلی چه باشد. دستور javadoc را
با مسیر مطلق (یا مسیر نسبی به دایرکتوری فعلی) فایلهای سورسی که می‌خواهید
مستندسازی کنید اجرا نمایید.
javadoc -d /home/html /home/src/java/awt/Button.java
/home/src/java/awt/Graphics*.java
مستندسازی بسته‌ها و کلاس‌ها
می‌توانید کل بسته‌ها و کلاس‌های منفرد را به طور همزمان مستندسازی کنید. در
اینجا مثالی ارائه شده که دو مورد از مثال‌های پیشین را ترکیب می‌کند.
می‌توانید از گزینهٔ -sourcepath برای مسیر بسته‌ها استفاده کنید اما نه برای
مسیر کلاس‌های منفرد.
javadoc -d /home/html -sourcepath /home/src java.awt
/home/src/java/applet/Applet.java
نسخه‌های خط فرمان و makefile زیر از دستور javadoc بر روی APIهای پلتفرم
Java اجرا می‌شوند. این دستور برای تولید مستندات برای حدود ۱۵۰۰ کلاس
public و protected در Java SE 1.2 به ۱۸۰ مگابایت حافظه نیاز دارد. هر دو
مثال از مسیرهای مطلق در آرگومان‌های گزینه‌ها استفاده می‌کنند، به طوری که
می‌توان همان دستور javadoc را از هر دایرکتوری اجرا کرد.
مثال خط فرمان
دستور زیر ممکن است برای برخی از شل‌ها بیش از حد طولانی باشد. برای غلبه
بر این محدودیت می‌توانید از یک فایل آرگومان خط فرمان استفاده کنید (یا یک
اسکریپت شل بنویسید).
در این مثال، packages نام فایلی است که بسته‌های مورد پردازش، مانند
java.appletjava.lang را در بر دارد. هیچ‌یک از گزینه‌ها نباید شامل نویسه
خط جدید بین علامت‌های نقل‌قول تکی باشد. برای مثال، اگر این نمونه را
رونوشت و جای‌گذاری می‌کنید، نویسه‌های خط جدید را از گزینه -bottom حذف
کنید.
javadoc -sourcepath /java/jdk/src/share/classes \
-overview /java/jdk/src/share/classes/overview.html \
-d /java/jdk/build/api \
-use \
-splitIndex \
-windowtitle 'Java Platform, Standard Edition 7 API Specification' \
-doctitle 'Java Platform, Standard Edition 7 API Specification' \
-header '<b>Java™ SE 7</b>' \
-bottom '<font size="-1">
<a href="http://bugreport.sun.com/bugreport">Submit a bug or feature</a><br/>
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
Other names may be trademarks of their respective owners.</font>' \
-group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \
-group "Extension Packages" "javax.*" \
-J-Xmx180m \
@packages
رابط برنامه‌نویسی
رابط Javadoc Access API کاربر را قادر می‌سازد تا ابزار Javadoc را
مستقیماً از یک برنامه Java و بدون اجرای یک پردازش جدید فراخوانی کند.
برای مثال، عبارت‌های زیر معادل دستور javadoc -d /home/html -sourcepath
/home/src -subpackages java -exclude java.net:java.lang com.example
هستند:
import javax.tools.DocumentationTool;
import javax.tools.ToolProvider;
public class JavaAccessSample{
public static void main(String[] args){
DocumentationTool javadoc = ToolProvider.getSystemDocumentationTool();
int rc = javadoc.run( null, null, null,
"-d", "/home/html",
"-sourcepath", "home/src",
"-subpackages", "java",
"-exclude", "java.net:java.lang",
"com.example");
}
}
سه آرگومان نخست متد run، جریان‌های ورودی، خروجی استاندارد و خطای
استاندارد را مشخص می‌کنند. مقدار پیش‌فرض برای هر یک از System.in،
System.out و System.err به ترتیب برابر با Null است.
مثال MAKEFILE (THE MAKEFILE EXAMPLE)
این یک نمونه از یک makefile در GNU است. علامت‌های نقل‌قول تکی دور
آرگومان‌های makefile قرار می‌گیرند. برای دیدن یک مثال از makefile ویندوز،
بخش makefiles از Javadoc FAQ را در
http://www.oracle.com/technetwork/java/javase/documentation/index-137483.html#makefiles
ببینید.
javadoc -sourcepath $(SRCDIR) \ /* Sets path for source files */
-overview $(SRCDIR)/overview.html \ /* Sets file for overview text */
-d /java/jdk/build/api \ /* Sets destination directory */
-use \ /* Adds "Use" files */
-splitIndex \ /* Splits index A-Z */
-windowtitle $(WINDOWTITLE) \ /* Adds a window title */
-doctitle $(DOCTITLE) \ /* Adds a doc title */
-header $(HEADER) \ /* Adds running header text */
-bottom $(BOTTOM) \ /* Adds text at bottom */
-group $(GROUPCORE) \ /* 1st subhead on overview page */
-group $(GROUPEXT) \ /* 2nd subhead on overview page */
-J-Xmx180m \ /* Sets memory to 180MB */
java.lang java.lang.reflect \ /* Sets packages to document */
java.util java.io java.net \
java.applet
WINDOWTITLE = 'Java™ SE 7 API Specification'
DOCTITLE = 'Java™ Platform Standard Edition 7 API Specification'
HEADER = '<b>Java™ SE 7</font>'
BOTTOM = '<font size="-1">
<a href="http://bugreport.sun.com/bugreport">Submit a bug or feature</a><br/>
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
Other names may be trademarks of their respective owners.</font>'
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
GROUPEXT = '"Extension Packages" "javax.*"'
SRCDIR = '/java/jdk/1.7.0/src/share/classes'
• اگر گزینهٔ -windowtitle را نادیده بگیرید، دستور javadoc عنوان سند را
در عنوان پنجره کپی می‌کند. متن گزینهٔ -windowtitle شبیه به گزینهٔ
-doctitle است، اما بدون برچسب‌های HTML تا از نمایش این برچسب‌ها به صورت
متن خام در عنوان پنجره جلوگیری شود.
• اگر گزینهٔ -footer را نادیده بگیرید، دستور javadoc متن سربرگ را در
پانویس کپی می‌کند.
• گزینه‌های مهم دیگری که ممکن است بخواهید استفاده کنید اما در مثال قبلی
نیازی به آنها نبود، گزینه‌های -classpath و -link هستند.
عیب‌یابی عمومی (GENERAL TROUBLESHOOTING)
• دستور javadoc تنها فایلهایی را می‌خواند که حاوی نام‌های معتبر کلاس
باشند. اگر دستور javadoc محتویات یک فایل را به‌درستی نمی‌خواند، بررسی
کنید که نام کلاس‌ها معتبر باشد. بخش Process Source Files را ببینید.
• برای اطلاعات در مورد باگ‌های رایج و نکات عیب‌یابی، پرسش‌های متداول
Javadoc را در نشانی
http://www.oracle.com/technetwork/java/javase/documentation/index-137483.html
ببینید.
خطاها و هشدارها (ERRORS AND WARNINGS)
پیام‌های خطا و هشدار به جای اشاره به خط خاصی در کامنت مستندسازی، حاوی
نام فایل و شماره خط مربوط به اعلان هستند.
برای مثال، پیام error: cannot read: Class1.java به این معنی است که
دستور javadoc در تلاش است تا Class1.java را در دایرکتوری جاری بارگذاری
کند. نام کلاس به همراه مسیر آن (مطلق یا نسبی) نمایش داده می‌شود.
محیط (ENVIRONMENT)
CLASSPATH
CLASSPATH متغیر محیطی است که مسیری را که دستور javadoc برای
یافتن فایلهای کلاس کاربری به کار می‌برد، فراهم می‌کند. این متغیر
محیطی توسط گزینهٔ -classpath رونویسی (override) می‌شود.
دایرکتوری‌ها را در Windows با یک نقطه‌ویرگول (semicolon) و در
Oracle Solaris با یک دونقطه (colon) از هم جدا کنید.
مثال Windows: .;C:\classes;C:\home\java\classes
مثال Oracle Solaris: .:/home/classes:/usr/local/java/classes.
همچنین ببینید (SEE ALSO)
• javac(1)
• java(1)
• jdb(1)
• javap(1)
اسناد مرتبط (RELATED DOCUMENTS)
• فناوری Javadoc در
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/index.html
• نحوه پیدا شدن کلاس‌ها در
http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html
• نحوه نوشتن کامنت‌های مستندسازی برای ابزار Javadoc در
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
• یادداشت URL، شناسه‌گرهای یکنواخت منبع در
http://www.ietf.org/rfc/rfc1738.txt
• استاندارد HTML، نمایش سند HTML (۴۱۹۷۲۶۵ و ۴۱۳۷۳۲۱)
http://www.w3.org/TR/REC-html40/charset.html#h-5.2.2
JDK 8 03 March 2015 javadoc(1)