کامنت‌های مستندسازی (Documentation Comments)

ابزار javadoc از کامنت مستندسازی (در صورت وجود) که بلافاصله پیش از شروع اعلان قرار دارد استفاده می‌کند؛ خواه این اعلان یک یادداشت (annotation)، تغییردهنده (modifier) یا نام در حال اعلان باشد. اگر چندین کامنت مستندسازی پیش از اعلان وجود داشته باشد، فقط آخرین مورد (نزدیک‌ترین به اعلان) استفاده خواهد شد. اگر هر کامنت مستندسازی بعد از شروع اعلان قرار گیرد، نادیده گرفته می‌شود. برای بررسی وجود هرگونه کامنت مستندسازی اضافی یا نابجا، کد مبدأ خود را با گزینهٔ -Xlint در javac، یا به‌طور دقیق‌تر با -Xlint:dangling-doc-comments کامپایل کنید. درون یک فایل مبدأ، می‌توانید با استفاده از @SuppressWarnings("dangling-doc-comments") روی یک اعلان دربرگیرندهٔ مناسب، هرگونه هشدار تولیدشده توسط این گزینه‌ها را نادیده بگیرید..SS "انطباق (Conformance)" داکلت استاندارد محتوای کامنت‌های مستندسازی را از نظر انطباق اعتبارسنجی نمی‌کند و همچنین تلاشی برای تصحیح هیچ خطایی در کامنت‌های مستندسازی انجام نمی‌دهد. به هر کاربری که javadoc را اجرا می‌کند توصیه می‌شود از مشکلاتی که ممکن است هنگام تولید خروجی‌های ناسازگار با استاندارد یا خروجی‌های حاوی محتوای اجرایی، مانند JavaScript رخ دهند، آگاه باشد. داکلت استاندارد قابلیت DocLint را برای کمک به توسعه‌دهندگان در تشخیص مشکلات رایج در کامنت‌های مستندسازی ارائه می‌دهد؛ اما با این حال توصیه می‌شود که خروجی تولیدشده با هر ابزار مناسب بررسی انطباق و دیگر ابزارهای بازبینی اعتبارسنجی شود.

برای جزئیات بیشتر پیرامون الزامات انطباق اسناد HTML5، به Conformance requirements for authors [https://html.spec.whatwg.org/multipage/introduction.html#conformance-requirements-for-authors] در مشخصات HTML5 مراجعه کنید. برای جزئیات بیشتر درباره مسائل امنیتی مربوط به صفحات وب، به صفحه Open Web Application Security Project (OWASP) [https://www.owasp.org] مراجعه کنید.

گزینه‌های استاندارد javadoc (Standard javadoc Options)

گزینه‌های اصلی javadoc زیر معادل گزینه‌های متناظر در javac هستند. برای توضیحات دقیق درباره استفاده از این گزینه‌ها، بخش Standard Options در javac را ببینید:

• --add-modules
• -bootclasspath
• --class-path، -classpath یا -cp
• --disable-line-doc-comments
• --enable-preview
• -encoding
• -extdirs
• --limit-modules
• --module
• --module-path یا -p
• --module-source-path
• --release
• --source یا -source
• --source-path یا -sourcepath
• --system
• --upgrade-module-path

گزینه‌های زیر گزینه‌های اصلی javadoc هستند که معادلی در بین گزینه‌های javac ندارند:

-breakiterator

جمله اول توضیحات را در یک کامنت مستندسازی با استفاده از یک نمونه از java.text.BreakIterator برای تشخیص پایان جمله محاسبه می‌کند. قوانین مورداستفاده به لوکال جاری بستگی دارد: به عنوان مثال، در زبان انگلیسی، پایان جمله پس از یک نقطه، علامت سؤال یا علامت تعجب که با یک فاصله دنبال شده و واژه بعدی با یک حرف بزرگ آغاز می‌شود، رخ می‌دهد. (این سازوکار برای مدیریت بیشتر اختصارات در نظر گرفته شده است، مانند "The serial no. is valid"، اما مواردی مانند "Mr. Smith" را مدیریت نخواهد کرد.)

-doclet class

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

-docletpath path

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

-exclude pkglist

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

--expand-requires (transitive|all)

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

--help، -help، -h یا -?

خلاصه‌ای از گزینه‌های استاندارد را چاپ می‌کند.

--help-extra یا -X

خلاصه‌ای از مجموعه گزینه‌های اضافی را چاپ می‌کند.

-Jflag

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

javadoc -J-version
java version "17" 2021-09-14 LTS
Java(TM) SE Runtime Environment (build 17+35-LTS-2724)
Java HotSpot(TM) 64-Bit Server VM (build 17+35-LTS-2724, mixed mode, sharing)

-locale name

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

-package

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

-private

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

-protected

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

-public

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

-quiet

پیام‌ها را بی‌صدا می‌کند تا تنها هشدارها و خطاها نمایش داده شوند و مشاهده آن‌ها آسان‌تر شود. همچنین از نمایش رشته version جلوگیری می‌کند.

--show-members value

مشخص می‌کند کدام اعضا (فیلدها، متدها یا سازنده‌ها) مستند شوند، که در آن value می‌تواند یکی از موارد زیر باشد:

--show-module-contents value

میزان جزئیات مستندسازی اعلانات ماژول را مشخص می‌کند، که در آن value می‌تواند api یا all باشد.

--show-packages value

مشخص می‌کند کدام بسته‌های ماژول مستند شوند، که در آن value می‌تواند بسته‌های exported یا all باشد.

--show-types value

مشخص می‌کند کدام نوع‌ها (کلاس‌ها، رابط‌ها و غیره) مستند شوند، که در آن value می‌تواند یکی از موارد زیر باشد:

-subpackages subpkglist

مستندات را از فایل‌های مبدأ موجود در بسته‌های مشخص‌شده و به‌صورت بازگشتی در زیربسته‌های آن‌ها تولید می‌کند. این گزینه هنگام افزودن زیربسته‌های جدید به کد مبدأ مفید است زیرا آن‌ها به‌طور خودکار گنجانده می‌شوند. هر آرگومان بسته، هرگونه زیربسته سطح‌بالا (مانند java) یا نام کامل یک بسته (مانند javax.swing) است که نیازی به داشتن فایل‌های مبدأ در درون خود ندارد. آرگومان‌ها در تمامی سیستم‌عامل‌ها با دو نقطه از یکدیگر جدا می‌شوند. استفاده از نویسه‌های عام (wildcard) مجاز نیست. از -sourcepath برای مشخص کردن محل یافتن بسته‌ها استفاده کنید. این گزینه فایل‌های مبدئی را که در درخت مبدأ قرار دارند اما به این بسته‌ها تعلق ندارند، پردازش نمی‌کند.

-verbose

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

--version

اطلاعات نسخه را چاپ می‌کند.

-Werror

در صورت بروز هرگونه هشدار، یک خطا گزارش می‌دهد.

توجه داشته باشید که اگر یک فایل مبدأ جاوا حاوی یک کلاس اعلام‌شده به‌صورت ضمنی (implicitly declared class) باشد، آن کلاس و اعضای public، protected و package آن صرف‌نظر از گزینه‌هایی مانند --show-types، --show-members، -private، -protected، -package و -public مستند خواهند شد. اگر --show-members با مقدار private مشخص شود یا اگر -private به کار رود، آن‌گاه تمامی اعضای private کلاس اعلام‌شده به‌صورت ضمنی نیز مستند خواهند شد..SS گزینه‌های اضافی javadoc نکته: گزینه‌های اضافی javadoc ممکن است بدون اطلاع قبلی تغییر کنند.

گزینه‌های اضافی javadoc زیر معادل گزینه‌های متناظر در javac هستند. برای توضیحات دقیق درباره نحوه استفاده از این گزینه‌ها، به بخش Extra Options در javac مراجعه کنید:

• --add-exports
• --add-reads
• --patch-module
• -Xmaxerrs
• -Xmaxwarns

گزینه‌های استاندارد برای Doclet استاندارد

گزینه‌های زیر توسط doclet استاندارد ارائه می‌شوند.

--add-script file

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

--add-stylesheet file

فایل file را به عنوان یک فایل شیوه‌نامه (stylesheet) اضافی به مستندات تولیدشده می‌افزاید. از این گزینه می‌توان یک یا چند بار برای مشخص کردن شیوه‌نامه‌های اضافی گنجانده‌شده در مستندات استفاده کرد.

--allow-script-in-comments

اجازه استفاده از جاوااسکریپت در کامنت‌های مستندات و گزینه‌هایی که مقدار آن‌ها html-code است را می‌دهد.

-author

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

-bottom html-code

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

-charset name

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

-d directory

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

-docencoding name

کدگذاری فایل‌های HTML تولیدشده را مشخص می‌کند. نام باید یک نام ترجیحی MIME باشد، همان‌طور که در IANA Registry, Character Sets [http://www.iana.org/assignments/character-sets] مشخص شده است.

-docfilessubdirs

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

-doctitle html-code

عنوانی را که باید در بالای فایل خلاصه نمای کلی (overview summary) قرار گیرد مشخص می‌کند. متن مشخص‌شده در برچسب title به صورت یک سرتیتر سطح یک و وسط‌چین، مستقیماً زیر نوار ناوبری قرار می‌گیرد. برچسب title می‌تواند شامل برچسب‌های HTML و فاصله‌های خالی باشد، اما در این صورت باید عنوان را درون علامت نقل‌قول قرار دهید. علامت‌های نقل‌قول داخلی در برچسب title باید با نویسه گریز (escape) درج شوند. برای مثال، javadoc -doctitle "<b>My Library</b><br>v1.0" com.mypackage.

-excludedocfilessubdir name1,name2...

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

-footer html-code

این گزینه دیگر پشتیبانی نمی‌شود و یک هشدار صادر می‌کند.

-group name g1,g2...

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

-header html-code

متن سربرگی را که باید در بالای هر فایل خروجی قرار گیرد مشخص می‌کند. این سربرگ در سمت راست نوار ناوبری قرار می‌گیرد. مقدار header می‌تواند شامل برچسب‌های HTML و فاصله‌های خالی باشد، اما در این صورت، header باید داخل علامت نقل‌قول قرار گیرد. برای علامت‌های نقل‌قول داخلی در سربرگ، از نویسه‌های گریز استفاده کنید. برای مثال، javadoc -header "<b>My Library</b><br>v1.0" com.mypackage..TP -helpfile filename فایلی حاوی متنی را مشخص می‌کند که هنگام کلیک روی پیوند HELP در نوار پیمایش نمایش داده خواهد شد. اگر این گزینه داده نشود، ابزار javadoc یک صفحه پیش‌فرض ایجاد می‌کند که استفاده خواهد شد.

-html5

این گزینه بی‌اثر (no-op) است و صرفاً برای سازگاری با نسخه‌های پیشین حفظ شده است.

--javafx یا -javafx

عملکرد JavaFX را فعال می‌کند. اگر کلاس‌های کتابخانه JavaFX در مسیر ماژول شناسایی شوند، این گزینه به‌طور پیش‌فرض فعال است.

-keywords

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

-link url

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

--link-modularity-mismatch (warn|info)

مشخص می‌کند که آیا مستندات خارجی با پیمانه‌ای‌بودن نادرست (مانند مستندات غیرماژولار برای یک کتابخانه ماژولار یا حالت برعکس) باید به عنوان هشدار (warn) گزارش شوند یا صرفاً یک پیام (info). رفتار پیش‌فرض، گزارش به صورت هشدار است.

-linkoffline url1 url2

این گزینه گونه‌ای از گزینه -link است. هر دوی آن‌ها پیوندهایی به مستندات تولید‌شده با javadoc برای کلاس‌های ارجاع‌شده خارجی ایجاد می‌کنند. می‌توانید چند گزینه -linkoffline را در یک اجرای ابزار javadoc تعیین کنید.

--link-platform-properties url

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

-linksource

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

public class Button extends Component implements Accessible

--main-stylesheet file یا -stylesheetfile file

مسیر یک فایل شیوه‌نامهٔ (stylesheet) جایگزین را مشخص می‌کند که شامل تعاریف سبک‌های CSS استفاده‌شده در مستندات تولیدشده است. این گزینه به شما اجازه می‌دهد مقدار پیش‌فرض را لغو (override) کنید. اگر این گزینه را مشخص نکنید، ابزار javadoc یک شیوه‌نامهٔ پیش‌فرض ایجاد کرده و از آن استفاده می‌کند. نام فایل می‌تواند هر نامی باشد و به stylesheet.css محدود نیست. گزینهٔ --main-stylesheet شکل ارجح است.

-nocomment

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

-nodeprecated

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

-nodeprecatedlist

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

--no-fonts

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

-nohelp

پیوند HELP را در نوار ناوبری بالای هر صفحهٔ تولیدشده حذف می‌کند.

-noindex

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

-nonavbar

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

--no-platform-links

از تولید پیوندها به مستندات پلتفرم جلوگیری می‌کند. این پیوندها به طور پیش‌فرض تولید می‌شوند.

-noqualifier name1,name2...

فهرست توصیف‌کننده‌ها (qualifiers) را از خروجی حذف می‌کند. نام بسته از جاهایی که نام کلاس‌ها یا رابط‌ها ظاهر می‌شود، برداشته خواهد شد. به دلایل تاریخی، : می‌تواند در هر کجای آرگومان به عنوان جداکننده به جای , استفاده شود.

-nosince

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

-notimestamp

برچسب زمانی (timestamp) را که در یک یادداشت HTML در نزدیکی بالای هر صفحه در HTML تولیدشده پنهان شده است، حذف می‌کند. گزینهٔ -notimestamp زمانی مفید است که می‌خواهید ابزار javadoc را روی دو پایگاه منبع مختلف اجرا کرده و آن‌ها را مقایسه کنید؛ چرا که از ایجاد تفاوت به دلیل برچسب‌های زمانی جلوگیری می‌کند (که در غیر این صورت در هر صفحه تفاوت ایجاد می‌کرد). برچسب زمانی شامل شمارهٔ انتشار ابزار javadoc است.

-notree

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

--override-methods (detail|summary)

متدهای بازنویسی‌شده (overridden) را در بخش‌های جزئیات یا خلاصه مستندسازی می‌کند. حالت پیش‌فرض detail است.

-overview filename

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

-serialwarn

هشدارهای زمان کامپایل را برای تگ‌های ناموجود @serial گزارش می‌کند. به طور پیش‌فرض، Javadoc هیچ هشدار سریال‌سازی‌ای گزارش نمی‌کند. از این گزینه برای نمایش هشدارهای سریال‌سازی استفاده کنید که به مستندسازی مناسب فیلدهای پیش‌فرض قابل سریال‌سازی و متدهای writeExternal کمک می‌کند.

--since release(,release)*

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

--since-label text

متن (text) مورد استفاده در عنوان صفحهٔ "New API" را مشخص می‌کند. این متن می‌تواند حاوی اطلاعاتی در مورد انتشارهای پوشش‌داده‌شده در صفحه باشد، مانند "New API in release 2.0" یا "New API since release 1".

--snippet-path snippetpathlist

مسیرهای جستجو را برای یافتن فایل‌های مربوط به قطعه‌کدهای (snippets) خارجی مشخص می‌کند. snippetpathlist می‌تواند شامل چندین مسیر باشد که با جداکنندهٔ مسیر پلتفرم جدا شده‌اند (; در Windows و : در سایر پلتفرم‌ها). داکلت استاندارد ابتدا زیردایرکتوری snippet-files را در بسته‌ای که حاوی قطعه‌کد است جستجو می‌کند و سپس تمام دایرکتوری‌های موجود در فهرست داده‌شده را جستجو می‌نماید..TP -sourcetab tab-length تعداد فاصله‌هایی (spaces) را که هر tab در کد منبع استفاده می‌کند مشخص می‌کند.

--spec-base-url url

آدرس پایه (base URL) را برای URLهای نسبی در تگ‌های @spec مشخص می‌کند، تا هنگام تولید پیوندها به مشخصات فنی (specifications) خارجی استفاده شود. این آدرس می‌تواند یک URL مطلق یا یک URL نسبی باشد؛ در حالت دوم، نسبت به دایرکتوری پایهٔ فایل‌های خروجیِ تولیدشده ارزیابی می‌شود. مقدار پیش‌فرض معادل {@docRoot}/../specs است.

-splitindex

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

--syntax-highlight

برجسته‌سازی ساختار نحوی (syntax highlighting) را برای قطعه‌کدهای موجود در تگ‌های {@snippet} و عناصر <pre><code> فعال می‌کند. برای snippetها، از صفت lang برای تعیین زبان قطعه‌کدها استفاده می‌شود که مقدار پیش‌فرض آن برای snippetهای درون‌خطی (inline) برابر با "java" است و برای snippetهای خارجی از پسوند فایل استخراج می‌شود. در تگ‌های <pre><code> مربوط به HTML، صفت class می‌تواند برای مشخص کردن زبان قطعه‌کدِ محصورشده مطابق شکل زیر استفاده شود:

-tag name:locations:header

یک تگ سفارشی را با یک تک‌آرگومان مشخص می‌کند. برای این‌که ابزار javadoc بتواند املای نام‌های تگ را بررسی کند، لازم است برای هر تگ سفارشی که در کد منبع وجود دارد یک گزینهٔ -tag لحاظ شود، و مواردی که در اجرای جاری در خروجی درج نمی‌شوند، غیرفعال گردند (با X). علامت دونقطه (:) همیشه جداکننده است. برای گنجاندن دونقطه در نام تگ، آن را با یک ممیز برعکس یا بک‌اسلش (\) فراردهی (escape) کنید. گزینهٔ -tag سرآیند تگ، header، را به‌صورت پررنگ (bold) چاپ می‌کند که در سطر بعدی متن حاصل از تک‌آرگومان آن آورده می‌شود. مشابه هر تگ بلوکی (block tag)، متن آرگومان می‌تواند شامل تگ‌های درون‌خطی باشد که آن‌ها نیز تفسیر می‌شوند. خروجی شبیه به تگ‌های تک‌آرگومانهٔ استاندارد مانند تگ‌های @return و @author است. حذف کردن مقدار header باعث می‌شود که name به‌عنوان سرآیند قرار گیرد. پارامتر locations فهرستی از نویسه‌ها است که انواع اعلان‌هایی را که تگ می‌تواند در آن‌ها به کار رود مشخص می‌کند. نویسه‌های زیر را می‌توان با حروف بزرگ یا کوچک استفاده کرد:

-taglet class

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

-tagletpath tagletpathlist

مسیرهای جستجو برای یافتن فایل‌های کلاس taglet را مشخص می‌کند. پارامتر tagletpathlist می‌تواند شامل چندین مسیر باشد که با جداکنندهٔ مسیرهای پلتفرم از هم جدا می‌شوند (; در Windows؛ : در سایر پلتفرم‌ها). ابزار javadoc تمام زیردایرکتوری‌های مسیرهای مشخص‌شده را جستجو می‌کند.

-top html-code

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

-use

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

-version

متن تمام تگ‌های version را در مستندات تولیدشده لحاظ می‌کند. این متن به‌صورت پیش‌فرض حذف می‌شود. نکته: برای آگاهی از نسخهٔ ابزار javadoc که استفاده می‌کنید، از گزینهٔ --version (با دو خط تیره) استفاده کنید.

-windowtitle title

عنوانی را که باید در تگ <title> در HTML قرار گیرد مشخص می‌کند. متن مشخص‌شده در تگ title در عنوان پنجره و در هر نشانک مرورگر (لیست علاقه‌مندی‌ها) که شخصی برای این صفحه ایجاد کند، نمایش داده می‌شود. این عنوان نباید حاوی هیچ تگ HTML باشد زیرا مرورگر آن‌ها را به‌درستی تفسیر نخواهد کرد. برای هر نقل‌قول داخلی در تگ title از نویسه‌های فرار (escape characters) استفاده کنید. اگر گزینهٔ -windowtitle حذف شود، ابزار javadoc از مقدار گزینهٔ -doctitle برای گزینهٔ -windowtitle استفاده می‌کند. برای مثال: javadoc -windowtitle "My Library" com.mypackage..SS گزینه‌های اضافی برای Standard Doclet موارد زیر گزینه‌های اضافی ارائه‌شده توسط Standard Doclet هستند و ممکن است بدون اطلاع قبلی تغییر کنند. گزینه‌های اضافی کمتر استفاده می‌شوند یا به عنوان گزینه‌های پیشرفته در نظر گرفته می‌شوند.

--date date-and-time

مقداری را برای برچسب زمانی (timestamp) صفحه‌های تولیدشده در قالب ISO 8601 [https://www.iso.org/iso-8601-date-and-time-format.html] مشخص می‌کند. مقدار مشخص‌شده باید در بازهٔ ۱۰ سال نسبت به تاریخ و زمان کنونی باشد. مشخص کردن هر دو گزینهٔ -notimestamp و --date به طور هم‌زمان یک خطا است. استفاده از یک مقدار مشخص موجب می‌شود که مستندات تولیدشده بتوانند بخشی از یک ساخت بازتولیدپذیر [https://reproducible-builds.org] باشند. در صورت مشخص نشدن این گزینه، مقدار پیش‌فرض تاریخ و زمان کنونی خواهد بود. برای نمونه:

--legal-notices (default|none|directory)

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

--no-frames

این گزینه دیگر پشتیبانی نمی‌شود و یک هشدار صادر می‌کند.

-Xdoclint

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

-Xdoclint:flag,flag,...

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

-Xdoclint/package:[-]packages

بررسی‌ها را در بسته‌های مشخص فعال یا غیرفعال می‌کند. packages فهرستی از مشخص‌کننده‌های بسته است که با کاما از هم جدا شده‌اند. یک مشخص‌کننده بسته یا نام کامل یک بسته است یا پیشوندی از نام بسته به همراه *، که به تمام زیربسته‌های آن بسته بسط می‌یابد. برای غیرفعال کردن بررسی‌ها برای بسته‌های مشخص‌شده، پیشوند - را به مشخص‌کننده بسته اضافه کنید.

-Xdocrootparent url

تمام موارد @docRoot را که پس از آن‌ها /.. در کامنت‌های مستندسازی آمده است، با url جایگزین می‌کند..SH DOCLINT ابزار DocLint امکان بررسی مشکلات احتمالی در کامنت‌های مستندسازی را فراهم می‌کند. مشکلات ممکن است بسته به شدت آن‌ها، به عنوان هشدار یا خطا گزارش شوند. برای نمونه، نبود یک کامنت ممکن است سبک نگارش بدی باشد که مستحق یک هشدار است، اما پیوند به یک اعلان ناشناخته در Java جدی‌تر بوده و سزاوار خطا است. مشکلات در گروه‌ها سازمان‌دهی شده‌اند، و می‌توان از گزینه‌ها برای فعال یا غیرفعال کردن پیام‌ها در یک یا چند گروه استفاده کرد. درون کد منبع، می‌توان پیام‌های یک یا چند گروه را با استفاده از حاشیه‌نویسی‌های @SuppressWarnings نادیده گرفت.

هنگامی که از javadoc فراخوانی می‌شود، DocLint به‌طور پیش‌فرض تمام کامنت‌هایی را که در مستندات تولیدشده به کار رفته‌اند بررسی می‌کند. از این رو، برای تعیین این‌که کدام اعلان‌ها و کدام کامنت‌های مستندسازی متناظر گنجانده شوند، به سایر گزینه‌های خط فرمان متکی است. نکته: این امر ممکن است بدین معنی باشد که حتی کامنت‌های برخی از اعضای خصوصی (private) کلاس‌های سریال‌پذیر (serializable) نیز در صورتی که نیاز به مستندسازی در صفحهٔ تولیدشدهٔ Serialized Forms داشته باشند، بررسی خواهند شد.

در مقابل، هنگامی که DocLint از javac فراخوانی می‌شود، صرفاً به گزینه‌های مختلف -Xdoclint... متکی است تا مشخص کند کدام کامنت‌های مستندسازی بررسی شوند.

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

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

گروه‌ها (GROUPS)

بررسی‌های انجام‌شده توسط DocLint در گروه‌هایی سازمان‌دهی شده‌اند. هشدارها و خطاهای هر گروه را می‌توان با گزینه‌های خط فرمان فعال یا غیرفعال کرد، یا با استفاده از حاشیه‌نویسی‌های @SuppressWarnings نادیده گرفت.

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

•

accessibility --- بررسی مشکلات مربوط به دسترسی‌پذیری. برای نمونه، مشخص نشدن ویژگی alt در یک عنصر <img>، یا مشخص نشدن ویژگی‌های caption یا summary در یک عنصر <table>.

•

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

•

missing --- بررسی نبود کامنت‌ها یا تگ‌های مستندسازی. برای نمونه، نبود کامنت در اعلان یک کلاس، یا نبود تگ @param یا @return در کامنت اعلان یک متد.

•

reference --- بررسی مشکلات مربوط به ارجاعات به عناصر Java API از طریق تگ‌های کامنت مستندسازی. برای نمونه، مرجع موجود در @see یا {@link ...} یافت نشود، یا نام نامعتبری برای @param یا @throws داده شده باشد.

•

syntax --- بررسی مشکلات نحوی سطح‌پایین در کامنت‌های مستندسازی. برای نمونه، علامت‌های نامتقارن یا فرار داده‌نشدهٔ بزرگ‌تر و کوچک‌تر (< و >)، علامت‌های امپرسند (&) و تگ‌های نامعتبر کامنت مستندسازی.

مقایسه با ابزارهای اعتبارسنجی پایین‌دستی (Comparison with downstream validation tools)

ابزار DocLint یک ابزار تعبیه‌شده در javac و javadoc است که محتوای کامنت‌های مستندسازی را همان‌گونه که در فایل‌های منبع هستند بررسی می‌کند. در مقابل، از ابزارهای اعتبارسنجی پایین‌دستی می‌توان برای اعتبارسنجی خروجی تولیدشده از آن کامنت‌های مستندسازی توسط javadoc و doclet استاندارد استفاده کرد.

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

• ابزارهای اعتبارسنجی پایین‌دستی می‌توانند نتیجه نهایی هر مستندات تولیدشده را همان‌طور که توسط کاربر نهایی دیده خواهد شد بررسی کنند. این امر شامل محتوا از تمام منابع، از جمله کامنت‌های مستندسازی، خودِ doclet استاندارد، tagletهای ارائه‌شده توسط کاربر و محتوای ارائه‌شده از طریق گزینه‌های خط فرمان می‌شود. از آنجا که چنین ابزارهایی صفحات کامل HTML را تجزیه و تحلیل می‌کنند، می‌توانند بررسی‌های کامل‌تری نسبت به DocLint انجام دهند. با این حال، هنگامی که مشکلی در صفحات تولیدشده یافت می‌شود، ردیابی دقیق این که در کجای خط لوله ساخت (build pipeline) مشکل باید رفع شود، می‌تواند دشوارتر باشد.
• ابزار DocLint محتوای کامنت‌های مستندسازی را در فایل‌های منبع بررسی می‌کند. این امر شناسایی موقعیت دقیق هر مشکلی که ممکن است پیدا شود را بسیار آسان می‌سازد. ابزار DocLint همچنین می‌تواند برخی خطاهای معنایی را در کامنت‌های مستندسازی تشخیص دهد که ابزارهای پایین‌دستی قادر به تشخیص آن‌ها نیستند؛ مانند کامنت‌های مفقود، استفاده از برچسب @return در متدی با مقدار بازگشتی void، یا برچسب @param برای توصیف یک پارامتر ناموجود. اما با توجه به ماهیت خود، DocLint نمی‌تواند مشکلاتی مانند پیوندهای مفقود، خطاهای موجود در tagletهای سفارشیِ ارائه‌شده توسط کاربر، یا مشکلات درون خودِ doclet استاندارد را گزارش دهد. همچنین نمی‌تواند خطاها را در کامنت‌های مستندسازی در مرزهای میان محتوای موجود در یک کامنت مستندسازی و محتوای تولیدشده توسط یک taglet سفارشی به طور قابل‌اطمینان شناسایی کند.