\f[R] از عنصر \f[CR]\f[R] دریافت می‌شود.
اگر فایل یک فایل Markdown باشد، تمام محتوای فایل استفاده می‌شود.
عنوان صفحهٔ مرور کلی با \f[CR]\-doctitle\f[R] تنظیم می‌شود.
\f[I]نکته:\f[R] نسخه‌های قدیمی‌تر ابزار \f[CR]javadoc\f[R] فرض می‌کردند که هرگونه استفاده از این گزینه برای یک فایل HTML است، و هر پسوندی را برای \f[I]filename\f[R] مجاز می‌دانستند.
.RE
.TP
\f[CR]\-serialwarn\f[R]
هشدارهای زمان کامپایل را برای تگ‌های ناموجود \f[CR]\(atserial\f[R] گزارش می‌کند.
به طور پیش‌فرض، Javadoc هیچ هشدار سریال‌سازی‌ای گزارش نمی‌کند.
از این گزینه برای نمایش هشدارهای سریال‌سازی استفاده کنید که به مستندسازی مناسب فیلدهای پیش‌فرض قابل سریال‌سازی و متدهای \f[CR]writeExternal\f[R] کمک می‌کند.
.TP
\f[CR]\-\-since\f[R] \f[I]release\f[R](\f[CR],\f[R]\f[I]release\f[R])*
برای APIهایی که در \f[I]release\f[R]های مشخص‌شده اضافه شده یا به تازگی منسوخ شده‌اند، مستندات تولید می‌کند.
.RS
اگر تگ \f[CR]\(atsince\f[R] در یادداشت \f[CR]javadoc\f[R] یک عنصر در کد منبع مستندشده با یک \f[I]release\f[R] ارائه‌شده به عنوان آرگومان گزینه مطابقت داشته باشد، اطلاعات مربوط به آن عنصر و انتشاری که در آن اضافه شده است در صفحهٔ \(dqNew API\(dq گنجانده می‌شود.
اگر صفحهٔ \(dqDeprecated API\(dq تولید شود و عنصر \f[CR]since\f[R] از یادداشت (annotation) \f[CR]java.lang.Deprecated\f[R] یک عنصر مستندشده با یک \f[I]release\f[R] در آرگومان‌های گزینه مطابقت داشته باشد، اطلاعات مربوط به انتشاری که عنصر در آن منسوخ شده است به صفحهٔ \(dqDeprecated API\(dq اضافه می‌شود.
نسخه‌های انتشار با استفاده از مقایسهٔ رشته‌ای حساس به حروف کوچک و بزرگ مقایسه می‌شوند.
.RE
.TP
\f[CR]\-\-since\-label\f[R] \f[I]text\f[R]
متن (\f[I]text\f[R]) مورد استفاده در عنوان صفحهٔ \(dqNew API\(dq را مشخص می‌کند.
این متن می‌تواند حاوی اطلاعاتی در مورد انتشارهای پوشش‌داده‌شده در صفحه باشد، مانند
\(dqNew API in release 2.0\(dq یا \(dqNew API since release 1\(dq.
.TP
\f[CR]\-\-snippet\-path\f[R] \f[I]snippetpathlist\f[R]
مسیرهای جستجو را برای یافتن فایل‌های مربوط به قطعه‌کدهای (snippets) خارجی مشخص می‌کند.
\f[I]snippetpathlist\f[R] می‌تواند شامل چندین مسیر باشد که با جداکنندهٔ مسیر پلتفرم جدا شده‌اند (\f[CR];\f[R] در Windows و \f[CR]:\f[R] در سایر پلتفرم‌ها).
داکلت استاندارد ابتدا زیردایرکتوری \f[CR]snippet\-files\f[R] را در بسته‌ای که حاوی قطعه‌کد است جستجو می‌کند و سپس تمام دایرکتوری‌های موجود در فهرست داده‌شده را جستجو می‌نماید..TP
\f[CR]\-sourcetab\f[R] \f[I]tab\-length\f[R]
تعداد فاصله‌هایی (spaces) را که هر tab در کد منبع استفاده می‌کند مشخص می‌کند.
.TP
\f[CR]\-\-spec\-base\-url\f[R] \f[I]url\f[R]
آدرس پایه (base URL) را برای URLهای نسبی در تگ‌های \f[CR]\(atspec\f[R] مشخص می‌کند، تا هنگام تولید پیوندها به مشخصات فنی (specifications) خارجی استفاده شود.
این آدرس می‌تواند یک URL مطلق یا یک URL نسبی باشد؛ در حالت دوم، نسبت به دایرکتوری پایهٔ فایل‌های خروجیِ تولیدشده ارزیابی می‌شود.
مقدار پیش‌فرض معادل \f[CR]{\(atdocRoot}/../specs\f[R] است.
.TP
\f[CR]\-splitindex\f[R]
فایل نمایه (index) را به چند فایل تقسیم می‌کند؛ به‌صورت الفبایی، یک فایل برای هر حرف، به‌علاوه یک فایل برای تمام مدخل‌های نمایه‌ای که با نمادهای غیرالفبایی شروع می‌شوند.
.TP
\f[CR]\-\-syntax\-highlight\f[R]
برجسته‌سازی ساختار نحوی (syntax highlighting) را برای قطعه‌کدهای موجود در تگ‌های \f[CR]{\(atsnippet}\f[R] و عناصر \f[CR]\f[R] فعال می‌کند.
برای snippetها، از صفت \f[CR]lang\f[R] برای تعیین زبان قطعه‌کدها استفاده می‌شود که مقدار پیش‌فرض آن برای snippetهای درون‌خطی (inline) برابر با \(dqjava\(dq است و برای snippetهای خارجی از پسوند فایل استخراج می‌شود.
در تگ‌های \f[CR]\f[R] مربوط به HTML، صفت \f[CR]class\f[R] می‌تواند برای مشخص کردن زبان قطعه‌کدِ محصورشده مطابق شکل زیر استفاده شود:
.RS
.IP
.EX
...
.EE
اگر هیچ‌یک از این صفت‌ها در دسترس نباشد، تشخیص خودکار زبان اعمال می‌شود.
برای غیرفعال کردن برجسته‌سازی نحوی برای یک قطعه‌کد، زبان را با استفاده از یکی از سازوکارهای شرح‌داده‌شده در بالا روی \(dqtext\(dq تنظیم کنید.
زبان‌ها و قالب‌های پشتیبانی‌شده توسط این گزینه عبارتند از Java، Properties، JSON، HTML و XML.
.RE
.TP
\f[CR]\-tag\f[R] \f[I]name\f[R]:\f[I]locations\f[R]:\f[I]header\f[R]
یک تگ سفارشی را با یک تک‌آرگومان مشخص می‌کند.
برای اینکه ابزار \f[CR]javadoc\f[R] بتواند املای نام‌های تگ را بررسی کند، لازم است برای هر تگ سفارشی که در کد منبع وجود دارد یک گزینهٔ \f[CR]\-tag\f[R] لحاظ شود، و مواردی که در اجرای جاری در خروجی درج نمی‌شوند، غیرفعال گردند (با \f[CR]X\f[R]).
علامت دونقطه (\f[CR]:\f[R]) همیشه جداکننده است.
برای گنجاندن دونقطه در نام تگ، آن را با یک ممیز برعکس یا بک‌اسلش (\f[CR]\(rs\f[R]) فراردهی (escape) کنید.
گزینهٔ \f[CR]\-tag\f[R] سرآیند تگ، \f[I]header\f[R]، را به‌صورت پررنگ (bold) چاپ می‌کند که در سطر بعدی متن حاصل از تک‌آرگومان آن آورده می‌شود.
مشابه هر تگ بلوکی (block tag)، متن آرگومان می‌تواند شامل تگ‌های درون‌خطی باشد که آن‌ها نیز تفسیر می‌شوند.
خروجی شبیه به تگ‌های تک‌آرگومانهٔ استاندارد مانند تگ‌های \f[CR]\(atreturn\f[R] و \f[CR]\(atauthor\f[R] است.
حذف کردن مقدار \f[I]header\f[R] باعث می‌شود که \f[I]name\f[R] به‌عنوان سرآیند قرار گیرد.
پارامتر \f[I]locations\f[R] فهرستی از نویسه‌ها است که انواع اعلان‌هایی را که تگ می‌تواند در آن‌ها به کار رود مشخص می‌کند.
نویسه‌های زیر را می‌توان با حروف بزرگ یا کوچک استفاده کرد:
.RS
.IP \(bu 2
\f[CR]A\f[R]: همهٔ اعلان‌ها
.IP \(bu 2
\f[CR]C\f[R]: سازنده‌ها (constructors)
.IP \(bu 2
\f[CR]F\f[R]: فیلدها (fields)
.IP \(bu 2
\f[CR]M\f[R]: متدها (methods)
.IP \(bu 2
\f[CR]O\f[R]: صفحهٔ مرور کلی (overview) و سایر فایل‌های مستندات در زیردایرکتوری‌های \f[CR]doc\-files\f[R]
.IP \(bu 2
\f[CR]P\f[R]: بسته‌ها (packages)
.IP \(bu 2
\f[CR]S\f[R]: ماژول‌ها (modules)
.IP \(bu 2
\f[CR]T\f[R]: نوع‌ها (کلاس‌ها و رابط‌ها)
.IP \(bu 2
\f[CR]X\f[R]: هیچ‌جا: تگ غیرفعال است و نادیده گرفته خواهد شد
ترتیبی که تگ‌ها در خط فرمان وارد می‌شوند، به‌عنوان ترتیب نمایش آن‌ها در خروجیِ تولیدشده به کار خواهد رفت.
می‌توانید تگ‌های استاندارد را با ترتیبی که در خط فرمان مشخص شده با استفاده از گزینهٔ \f[CR]\-tag\f[R] بدون \f[I]locations\f[R] یا \f[I]header\f[R] لحاظ کنید.
.RE
.TP
\f[CR]\-taglet\f[R] \f[I]class\f[R]
نام کامل و رسمی (fully qualified name) مربوط به taglet مورد استفاده در تولید مستندات برای آن تگ را مشخص می‌کند.
برای مقدار \f[I]class\f[R] از نام کامل استفاده کنید.
این taglet همچنین تعداد آرگومان‌های متنی تگ سفارشی را تعیین می‌کند.
مورد taglet آن آرگومان‌ها را دریافت کرده، پردازش می‌کند و خروجی را تولید می‌نماید.
.RS
مفهوم Taglet برای تگ‌های بلوکی یا درون‌خطی کاربرد دارد.
آن‌ها می‌توانند هر تعداد آرگومان داشته باشند و رفتارهای سفارشی را پیاده‌سازی کنند، مانند پررنگ کردن متن، قالب‌بندی نقطه‌گلوله‌ها، نوشتن متن در یک فایل، یا راه‌اندازی فرآیندهای دیگر.
یک Taglet تنها می‌تواند تعیین کند که یک تگ در کجا و با چه قالبی ظاهر شود.
تمام تصمیم‌های دیگر توسط doclet گرفته می‌شود.
یک taglet نمی‌تواند کارهایی مانند حذف یک نام کلاس از فهرست کلاس‌های گنجانده‌شده را انجام دهد.
با این حال، می‌تواند اثرات جانبی (side effects) را اجرا کند؛ مانند چاپ متن تگ در یک فایل یا راه‌اندازی یک فرآیند دیگر.
از گزینهٔ \f[CR]\-tagletpath\f[R] برای مشخص کردن مسیر taglet استفاده کنید.
مثال زیر taglet مربوط به To Do را بعد از Parameters و قبل از Throws در صفحات تولیدشده درج می‌کند.
.IP
.EX
\-taglet com.sun.tools.doclets.ToDoTaglet
\-tagletpath /home/taglets
\-tag return
\-tag param
\-tag todo
\-tag throws
\-tag see
.EE
به‌عنوان روش جایگزین، می‌توانید از گزینهٔ \f[CR]\-taglet\f[R] به جای گزینهٔ \f[CR]\-tag\f[R] متناظر آن استفاده کنید، اما ممکن است خواندن آن دشوارتر باشد.
.RE
.TP
\f[CR]\-tagletpath\f[R] \f[I]tagletpathlist\f[R]
مسیرهای جستجو برای یافتن فایل‌های کلاس taglet را مشخص می‌کند.
پارامتر \f[I]tagletpathlist\f[R] می‌تواند شامل چندین مسیر باشد که با جداکنندهٔ مسیرهای پلتفرم از هم جدا می‌شوند (\f[CR];\f[R] در Windows؛ \f[CR]:\f[R] در سایر پلتفرم‌ها).
ابزار \f[CR]javadoc\f[R] تمام زیردایرکتوری‌های مسیرهای مشخص‌شده را جستجو می‌کند.
.TP
\f[CR]\-top\f[R] \f[I]html\-code\f[R]
متنی را که باید در بالای هر فایل خروجی قرار گیرد مشخص می‌کند.
.TP
\f[CR]\-use\f[R]
صفحات مربوط به کاربرد کلاس‌ها و بسته‌ها را ایجاد می‌کند.
یک صفحهٔ Use برای هر کلاس و بستهٔ مستندسازی‌شده لحاظ می‌کند.
این صفحه شرح می‌دهد چه بسته‌ها، کلاس‌ها، متدها، سازنده‌ها و فیلدهایی از هر API مربوط به کلاس یا بستهٔ مشخص‌شده استفاده می‌کنند.
به‌عنوان مثال برای کلاس C، مواردی که از کلاس C استفاده می‌کنند شامل زیرکلاس‌های C، فیلدهای تعریف‌شده از نوع C، متدهایی که C را برمی‌گردانند، و متدها و سازنده‌هایی با پارامترهایی از نوع C می‌شوند. برای نمونه، می‌توانید صفحهٔ Use را برای نوع \f[CR]String\f[R] بررسی کنید.
از آنجا که متد \f[CR]getName\f[R] در کلاس \f[CR]java.awt.Font\f[R] مقداری از نوع \f[CR]String\f[R] برمی‌گرداند، این متد از \f[CR]String\f[R] استفاده می‌کند و بنابراین متد \f[CR]getName\f[R] در صفحهٔ Use مربوط به \f[CR]String\f[R] ظاهر می‌شود.
این کار فقط کاربردهای API را مستند می‌کند، نه پیاده‌سازی داخلی آن را.
هنگامی که یک متد در پیاده‌سازی خود از \f[CR]String\f[R] استفاده می‌کند، اما رشته‌ای را به‌عنوان آرگومان دریافت نمی‌کند یا رشته‌ای برنمی‌گرداند، استفاده از \f[CR]String\f[R] محسوب نمی‌شود.
برای دسترسی به صفحهٔ تولیدشدهٔ Use، به کلاس یا بستهٔ مربوطه بروید و روی پیوند \f[B]USE\f[R] در نوار ناوبری کلیک کنید.
.TP
\f[CR]\-version\f[R]
متن تمام تگ‌های \f[CR]version\f[R] را در مستندات تولیدشده لحاظ می‌کند.
این متن به‌صورت پیش‌فرض حذف می‌شود.
نکته: برای آگاهی از نسخهٔ ابزار \f[CR]javadoc\f[R] که استفاده می‌کنید، از گزینهٔ \f[CR]\-\-version\f[R] (با دو خط تیره) استفاده کنید.
.TP
\f[CR]\-windowtitle\f[R] \f[I]title\f[R]
عنوانی را که باید در تگ \f[CR]\f[R] در HTML قرار گیرد مشخص می‌کند.
متن مشخص‌شده در تگ \f[CR]title\f[R] در عنوان پنجره و در هر نشانک مرورگر (لیست علاقه‌مندی‌ها) که شخصی برای این صفحه ایجاد کند، نمایش داده می‌شود.
این عنوان نباید حاوی هیچ تگ HTML باشد زیرا مرورگر آن‌ها را به‌درستی تفسیر نخواهد کرد.
برای هر نقل‌قول داخلی در تگ \f[CR]title\f[R] از نویسه‌های فرار (escape characters) استفاده کنید.
اگر گزینهٔ \f[CR]\-windowtitle\f[R] حذف شود، ابزار \f[CR]javadoc\f[R] از مقدار گزینهٔ \f[CR]\-doctitle\f[R] برای گزینهٔ \f[CR]\-windowtitle\f[R] استفاده می‌کند.
برای مثال:
\f[CR]javadoc \-windowtitle \(dqMy Library\(dq com.mypackage\f[R]..SS گزینه‌های اضافی برای Standard Doclet
موارد زیر گزینه‌های اضافی ارائه‌شده توسط Standard Doclet هستند و ممکن است بدون اطلاع قبلی تغییر کنند.
گزینه‌های اضافی کمتر استفاده می‌شوند یا به عنوان گزینه‌های پیشرفته در نظر گرفته می‌شوند.
.TP
\f[CR]\-\-date\f[R] \f[I]date\-and\-time\f[R]
مقداری را برای برچسب زمانی (timestamp) صفحه‌های تولیدشده در قالب
\f[B]ISO 8601\f[R]
[https://www.iso.org/iso\-8601\-date\-and\-time\-format.html] مشخص می‌کند.
مقدار مشخص‌شده باید در بازهٔ ۱۰ سال نسبت به تاریخ و زمان کنونی باشد.
مشخص کردن هر دو گزینهٔ \f[CR]\-notimestamp\f[R] و
\f[CR]\-\-date\f[R] به طور هم‌زمان یک خطا است.
استفاده از یک مقدار مشخص موجب می‌شود که مستندات تولیدشده بتوانند بخشی از یک
\f[B]ساخت بازتولیدپذیر\f[R] [https://reproducible\-builds.org] باشند.
در صورت مشخص نشدن این گزینه، مقدار پیش‌فرض تاریخ و زمان کنونی خواهد بود.
برای نمونه:
.RS
.IP
.EX
javadoc \-\-date 2022\-02\-01T17:41:59\-08:00 mypackage
.EE
.RE
.TP
\f[CR]\-\-legal\-notices\f[R] (\f[CR]default\f[R]|\f[CR]none\f[R]|\f[I]directory\f[R])
مکانی را مشخص می‌کند که فایل‌های حقوقی از آنجا در مستندات تولیدشده کپی شوند.
اگر این گزینه مشخص نشود یا با مقدار
\f[CR]default\f[R] استفاده گردد، فایل‌ها از مکان پیش‌فرض کپی می‌شوند.
اگر آرگومان با مقدار \f[CR]none\f[R] استفاده شود، هیچ فایلی کپی نخواهد شد.
هر آرگومان دیگر به عنوان دایرکتوری‌ای که فایل‌های حقوقی باید از آن کپی شوند تفسیر می‌شود.
.TP
\f[CR]\-\-no\-frames\f[R]
این گزینه دیگر پشتیبانی نمی‌شود و یک هشدار صادر می‌کند.
.TP
\f[CR]\-Xdoclint\f[R]
بررسی‌های توصیه‌شده برای مشکلات موجود در کامنت‌های مستندسازی را فعال می‌کند.
.RS
به طور پیش‌فرض، گزینهٔ \f[CR]\-Xdoclint\f[R] فعال است.
با گزینهٔ \f[CR]\-Xdoclint:none\f[R] آن را غیرفعال کنید.
برای جزئیات بیشتر، \f[B]DocLint\f[R] را ببینید.
.RE
.TP
\f[CR]\-Xdoclint:\f[R]\f[I]flag\f[R],\f[I]flag\f[R],...
بررسی‌های خاص برای انواع مختلف اشکالات در کامنت‌های مستندسازی را فعال یا غیرفعال می‌کند.
.RS
هر \f[I]flag\f[R] می‌تواند یکی از مقادیر \f[CR]all\f[R]، \f[CR]none\f[R]، یا
\f[CR][\-]\f[R]\f[I]group\f[R] باشد که در آن \f[I]group\f[R] یکی از
مقادیر زیر را دارد: \f[CR]accessibility\f[R]، \f[CR]html\f[R]،
\f[CR]missing\f[R]، \f[CR]reference\f[R]، \f[CR]syntax\f[R].
برای جزئیات بیشتر دربارهٔ این مقادیر، \f[B]DocLint Groups\f[R] را ببینید.
هنگام مشخص کردن دو یا چند پرچم، می‌توانید از یک گزینهٔ منفرد
\f[CR]\-Xdoclint:...\f[R] شامل تمام پرچم‌های مورد نظر استفاده کنید، یا
می‌توانید گزینه‌های متعددی را به کار ببرید که در هر کدام یک یا چند پرچم آمده است.
برای نمونه، از هر یک از دستورهای زیر برای بررسی اشکالات HTML، نحو (syntax) و دسترس‌پذیری در فایل \f[CR]MyFile.java\f[R] استفاده کنید:
.IP
.EX
javadoc \-Xdoclint:html \-Xdoclint:syntax \-Xdoclint:accessibility MyFile.java
javadoc \-Xdoclint:html,syntax,accessibility MyFile.java
.EE
مثال‌های زیر نحوهٔ تغییر موارد گزارش‌شده توسط DocLint را نشان می‌دهند:
.IP \(bu 2
\f[CR]\-Xdoclint:none\f[R] \-\-\- تمام بررسی‌ها را غیرفعال می‌کند
.IP \(bu 2
\f[CR]\-Xdoclint:\f[R]\f[I]group\f[R] \-\-\- بررسی‌های گروه \f[I]group\f[R] را فعال می‌کند
.IP \(bu 2
\f[CR]\-Xdoclint:all\f[R] \-\-\- تمام گروه‌های بررسی را فعال می‌کند
.IP \(bu 2
\f[CR]\-Xdoclint:all,\-\f[R]\f[I]group\f[R] \-\-\- تمام بررسی‌ها به جز بررسی‌های گروه \f[I]group\f[R] را فعال می‌کند
برای جزئیات بیشتر، \f[B]DocLint\f[R] را ببینید.
.RE
.TP
\f[CR]\-Xdoclint/package:\f[R][\f[CR]\-\f[R]]\f[I]packages\f[R]
بررسی‌ها را در بسته‌های مشخص فعال یا غیرفعال می‌کند.
\f[I]packages\f[R] فهرستی از مشخص‌کننده‌های بسته است که با کاما از هم جدا شده‌اند.
یک مشخص‌کننده بسته یا نام کامل یک بسته است یا پیشوندی از نام بسته به همراه \f[CR]*\f[R]، که به تمام زیربسته‌های آن بسته بسط می‌یابد.
برای غیرفعال کردن بررسی‌ها برای بسته‌های مشخص‌شده، پیشوند \f[CR]\-\f[R] را به مشخص‌کننده بسته اضافه کنید.
.RS
برای جزئیات بیشتر، \f[B]DocLint\f[R] را ببینید.
.RE
.TP
\f[CR]\-Xdocrootparent\f[R] \f[I]url\f[R]
تمام موارد \f[CR]\(atdocRoot\f[R] را که پس از آن‌ها \f[CR]/..\f[R] در کامنت‌های مستندسازی آمده است، با \f[I]url\f[R] جایگزین می‌کند..SH DOCLINT
ابزار DocLint امکان بررسی مشکلات احتمالی در کامنت‌های مستندسازی را فراهم
می‌کند.
مشکلات ممکن است بسته به شدت آن‌ها، به عنوان هشدار یا خطا گزارش شوند.
برای نمونه، نبود یک کامنت ممکن است سبک نگارش بدی باشد که مستحق یک هشدار
است، اما پیوند به یک اعلان ناشناخته در Java جدی‌تر بوده و سزاوار خطا
است.
مشکلات در \f[B]گروه‌ها\f[R] سازمان‌دهی شده‌اند، و می‌توان از گزینه‌ها برای
فعال یا غیرفعال کردن پیام‌ها در یک یا چند گروه استفاده کرد.
درون کد منبع، می‌توان پیام‌های یک یا چند گروه را با استفاده از حاشیه‌نویسی‌های
\f[CR]\(atSuppressWarnings\f[R] \f[B]نادیده گرفت\f[R].
.PP
هنگامی که از \f[CR]javadoc\f[R] فراخوانی می‌شود، DocLint به‌طور پیش‌فرض تمام
کامنت‌هایی را که در مستندات تولیدشده به کار رفته‌اند بررسی می‌کند.
از این رو، برای تعیین اینکه کدام اعلان‌ها و کدام کامنت‌های مستندسازی
متناظر گنجانده شوند، به سایر گزینه‌های خط فرمان متکی است.
\f[I]نکته:\f[R] این امر ممکن است بدین معنی باشد که حتی کامنت‌های برخی از
اعضای خصوصی (private) کلاس‌های سریال‌پذیر (serializable) نیز در صورتی که
نیاز به مستندسازی در صفحهٔ تولیدشدهٔ \f[CR]Serialized Forms\f[R] داشته
باشند، بررسی خواهند شد.
.PP
در مقابل، هنگامی که DocLint از \f[CR]javac\f[R] فراخوانی می‌شود، صرفاً به
گزینه‌های مختلف \f[CR]\-Xdoclint...\f[R] متکی است تا مشخص کند کدام
کامنت‌های مستندسازی بررسی شوند.
.PP
ابزار DocLint تلاشی برای تصحیح ورودی نامعتبر نمی‌کند، بلکه تنها آن را
گزارش می‌دهد.
.PP
\f[I]نکته:\f[R] ابزار DocLint کامل بودن این بررسی‌ها را تضمین نمی‌کند.
به‌ویژه، این ابزار یک اعتبارسنج کامل انطباق با HTML نیست.
هدف این است که تنها خطاهای رایج به روشی آسان گزارش شوند.
.SS "گروه‌ها (GROUPS)"
بررسی‌های انجام‌شده توسط DocLint در گروه‌هایی سازمان‌دهی شده‌اند.
هشدارها و خطاهای هر گروه را می‌توان با گزینه‌های خط فرمان فعال یا غیرفعال
کرد، یا با استفاده از حاشیه‌نویسی‌های \f[CR]\(atSuppressWarnings\f[R] نادیده
گرفت.
.PP
گروه‌ها به شرح زیر هستند:
.IP \(bu 2
\f[CR]accessibility\f[R] \-\-\- بررسی مشکلات مربوط به دسترسی‌پذیری.
برای نمونه، مشخص نشدن ویژگی \f[CR]alt\f[R] در یک عنصر \f[CR]<img>\f[R]، یا
مشخص نشدن ویژگی‌های caption یا summary در یک عنصر \f[CR]<table>\f[R].
.RS 2
.PP
اگر انتظار رود که یک ابزار اعتبارسنجی پایین‌دستی در فایل‌های تولیدشده توسط
\f[CR]javadoc\f[R] خطایی گزارش کند، مشکلات به عنوان خطا گزارش می‌شوند.
.PP
برای مرجع، \f[B]دستورالعمل‌های دسترسی‌پذیری محتوای وب\f[R]
[https://www.w3.org/WAI/standards\-guidelines/wcag] را ببینید.
.RE
.IP \(bu 2
\f[CR]html\f[R] \-\-\- تشخیص مشکلات رایج و سطح‌بالای HTML.
برای نمونه، قرار دادن عناصر بلوکی درون عناصر درون‌خطی، یا نبستن عناصری که
به تگ پایانی نیاز دارند.
.RS 2
.PP
اگر انتظار رود که یک ابزار اعتبارسنجی پایین‌دستی در فایل‌های تولیدشده توسط
\f[CR]javadoc\f[R] خطایی گزارش کند، مشکلات به عنوان خطا گزارش می‌شوند.
.PP
برای مرجع، \f[B]استاندارد زندهٔ HTML\f[R]
[https://html.spec.whatwg.org/multipage] را ببینید.
.RE
.IP \(bu 2
\f[CR]missing\f[R] \-\-\- بررسی نبود کامنت‌ها یا تگ‌های مستندسازی.
برای نمونه، نبود کامنت در اعلان یک کلاس، یا نبود تگ \f[CR]\(atparam\f[R] یا
\f[CR]\(atreturn\f[R] در کامنت اعلان یک متد.
.RS 2
.PP
مشکلات مربوط به موارد ناموجود معمولاً به عنوان هشدار گزارش می‌شوند، زیرا
بعید است توسط ابزارهای اعتبارسنجی پایین‌دستی که ممکن است برای بررسی خروجی
تولیدشده توسط \f[CR]javadoc\f[R] استفاده شوند، به عنوان خطا گزارش شوند.
.RE
.IP \(bu 2
\f[CR]reference\f[R] \-\-\- بررسی مشکلات مربوط به ارجاعات به عناصر
Java API از طریق تگ‌های کامنت مستندسازی.
برای نمونه، مرجع موجود در \f[CR]\(atsee\f[R] یا \f[CR]{\(atlink ...}\f[R]
یافت نشود، یا نام نامعتبری برای \f[CR]\(atparam\f[R] یا
\f[CR]\(atthrows\f[R] داده شده باشد.
.RS 2
.PP
مشکلات معمولاً به عنوان خطا گزارش می‌شوند؛ زیرا هرچند ممکن است این مشکل
باعث بروز نقص در فایل‌های تولیدشده نشود، اما نویسنده احتمالاً مرتکب اشتباهی
شده است که منجر به مستندات نادرست یا غیرمنتظره خواهد شد.
.RE
.IP \(bu 2
\f[CR]syntax\f[R] \-\-\- بررسی مشکلات نحوی سطح‌پایین در کامنت‌های مستندسازی.
برای نمونه، علامت‌های نامتقارن یا فرار داده‌نشدهٔ بزرگ‌تر و کوچک‌تر
(\f[CR]<\f[R] و \f[CR]>\f[R])، علامت‌های امپرسند (\f[CR]&\f[R]) و تگ‌های
نامعتبر کامنت مستندسازی.
.RS 2
.PP
مشکلات معمولاً به عنوان خطا گزارش می‌شوند زیرا ممکن است به مستندات نادرست
یا غیرمنتظره منجر شوند.
.RE.SS "فرونشاندن پیام‌ها (Suppressing Messages)"
ابزار DocLint دو رشته را که ممکن است در آرگومان‌های یادداشت \f[CR]\(atSuppressWarnings\f[R] وجود داشته باشند بررسی کرده و تشخیص می‌دهد.
.IP \(bu 2
\f[CR]doclint\f[R]
.IP \(bu 2
\f[CR]doclint:\f[R]\f[I]LIST\f[R]
.PP
که در آن \f[I]LIST\f[R] فهرستی از یک یا چند مورد جداشده با کاما از گزینه‌های
\f[CR]accessibility\f[R]، \f[CR]html\f[R]، \f[CR]missing\f[R]،
\f[CR]reference\f[R]، \f[CR]syntax\f[R] است.
.PP
نام‌های موجود در \f[I]LIST\f[R] همان نام‌های \f[B]گروه\f[R] (\f[B]group\f[R]) پشتیبانی‌شده توسط گزینه خط فرمان \f[CR]\-Xdoclint\f[R] برای \f[CR]javac\f[R]
و \f[CR]javadoc\f[R] هستند.
(این همان قراردادی است که توسط گزینه \f[CR]\-Xlint\f[R] در \f[CR]javac\f[R]
و نام‌های متناظر پشتیبانی‌شده توسط \f[CR]\(atSuppressWarnings\f[R] رعایت می‌شود.)
.PP
نام‌های موجود در \f[I]LIST\f[R] را می‌توان به طور معادل در آرگومان‌های جداگانه یادداشت نیز مشخص کرد.
برای مثال، موارد زیر معادل یکدیگرند:
.IP \(bu 2
\f[CR]\(atSuppressWarnings(\(dqdoclint:accessibility,missing\(dq)\f[R]
.IP \(bu 2
\f[CR]\(atSuppressWarnings(\(dqdoclint:accessibility\(dq, \(dqdoclint:missing\(dq)\f[R]
.PP
هنگامی که DocLint مشکلی را در یک کامنت مستندسازی تشخیص می‌دهد، وجود \f[CR]\(atSuppressWarnings\f[R] را روی اعلان مربوطه و تمام اعلان‌های دربرگیرنده از نظر لغوی (lexically enclosing) بررسی می‌کند.
اگر چنین یادداشتی حاوی رشته ساده \f[CR]doclint\f[R] یا شکل طولانی‌تر
\f[CR]doclint:LIST\f[R] یافت شود که در آن \f[I]LIST\f[R] حاوی نام گروه مربوط به آن مشکل باشد، از مشکل صرف‌نظر خواهد شد.
.PP
\f[I]نکته:\f[R] همانند سایر کاربردهای \f[CR]\(atSuppressWarnings\f[R]،
استفاده از این یادداشت روی اعلان یک ماژول یا بسته (package) فقط بر همان اعلان اثر می‌گذارد؛ و بر محتویات آن ماژول یا بسته در سایر فایل‌های منبع تأثیری ندارد.
.PP
تمامی پیام‌های مربوط به یک مشکل با وجود یادداشت مناسب \f[CR]\(atSuppressWarnings\f[R] فرونشانده می‌شوند: این امر شامل خطاها و همچنین هشدارها است.
.PP
\f[I]نکته:\f[R] تنها \f[I]فرونشاندن\f[R] پیام‌ها امکان‌پذیر است.
اگر یادداشت \f[CR]\(atSuppressWarnings(\(dqdoclint\(dq)\f[R] در یک اعلان سطح بالا (top\-level) مشخص شود، تمام پیام‌های DocLint برای آن اعلان و هر اعلان محصور در آن فرونشانده خواهند شد؛ فعال‌سازی مجدد و انتخابی پیام‌ها برای مشکلات موجود در اعلان‌های محصور ممکن نیست.
.SS "مقایسه با ابزارهای اعتبارسنجی پایین‌دستی (Comparison with downstream validation tools)"
ابزار DocLint یک ابزار تعبیه‌شده در \f[CR]javac\f[R] و \f[CR]javadoc\f[R] است
که محتوای کامنت‌های مستندسازی را همان‌گونه که در فایل‌های منبع هستند بررسی می‌کند.
در مقابل، از ابزارهای اعتبارسنجی پایین‌دستی می‌توان برای اعتبارسنجی خروجی تولیدشده از آن کامنت‌های مستندسازی توسط \f[CR]javadoc\f[R]
و doclet استاندارد استفاده کرد.
.PP
اگرچه در کارکردها تا حدی هم‌پوشانی وجود دارد، اما این دو سازوکار متفاوت هستند و هر یک نقاط قوت و ضعف خود را دارند.
.IP \(bu 2
ابزارهای اعتبارسنجی پایین‌دستی می‌توانند نتیجه نهایی هر مستندات تولیدشده را همان‌طور که توسط کاربر نهایی دیده خواهد شد بررسی کنند.
این امر شامل محتوا از تمام منابع، از جمله کامنت‌های مستندسازی، خودِ doclet استاندارد، tagletهای ارائه‌شده توسط کاربر و محتوای ارائه‌شده از طریق گزینه‌های خط فرمان می‌شود.
از آنجا که چنین ابزارهایی صفحات کامل HTML را تجزیه و تحلیل می‌کنند، می‌توانند بررسی‌های کامل‌تری نسبت به DocLint انجام دهند.
با این حال، هنگامی که مشکلی در صفحات تولیدشده یافت می‌شود، ردیابی دقیق این که در کجای خط لوله ساخت (build pipeline) مشکل باید رفع شود، می‌تواند دشوارتر باشد.
.IP \(bu 2
ابزار DocLint محتوای کامنت‌های مستندسازی را در فایل‌های منبع بررسی می‌کند.
این امر شناسایی موقعیت دقیق هر مشکلی که ممکن است پیدا شود را بسیار آسان می‌سازد.
ابزار DocLint همچنین می‌تواند برخی خطاهای معنایی را در کامنت‌های مستندسازی تشخیص دهد که ابزارهای پایین‌دستی قادر به تشخیص آن‌ها نیستند؛ مانند کامنت‌های مفقود، استفاده از برچسب \f[CR]\(atreturn\f[R] در متدی با مقدار بازگشتی \f[CR]void\f[R]، یا برچسب \f[CR]\(atparam\f[R] برای توصیف یک پارامتر ناموجود.
اما با توجه به ماهیت خود، DocLint نمی‌تواند مشکلاتی مانند پیوندهای مفقود، خطاهای موجود در tagletهای سفارشیِ ارائه‌شده توسط کاربر، یا مشکلات درون خودِ doclet استاندارد را گزارش دهد.
همچنین نمی‌تواند خطاها را در کامنت‌های مستندسازی در مرزهای میان محتوای موجود در یک کامنت مستندسازی و محتوای تولیدشده توسط یک taglet سفارشی به طور قابل‌اطمینان شناسایی کند.