'\" t .\" Copyright (c) 1994, 2015, Oracle and/or its affiliates. All rights reserved. .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. .\" .\" This code is free software; you can redistribute it and/or modify it .\" under the terms of the GNU General Public License version 2 only, as .\" published by the Free Software Foundation. .\" .\" This code is distributed in the hope that it will be useful, but WITHOUT .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License .\" version 2 for more details (a copy is included in the LICENSE file that .\" accompanied this code). .\" .\" You should have received a copy of the GNU General Public License version .\" 2 along with this work; if not, write to the Free Software Foundation, .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. .\" .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA .\" or visit www.oracle.com if you need additional information or have any .\" questions. .\" .\" Arch: generic .\" Software: JDK 8 .\" Date: 03 March 2015 .\" SectDesc: Basic Tools .\" Title: javadoc.1 .\" .if n .pl 99999 .TH javadoc 1 "03 March 2015" "JDK 8" "Basic Tools" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "نام (NAME)" javadoc \- تولید صفحات HTML مستندات API از فایل‌های منبع Java\&. .SH "خلاصه دستور (SYNOPSIS)" .sp .nf \fBjavadoc\fR {\fIpackages\fR|\fIsource\-files\fR} [\fIoptions\fR] [\fI@argfiles\fR] .fi .sp .TP \fIpackages\fR نام بسته‌هایی که می‌خواهید مستندسازی کنید، جدا شده با فاصله، برای نمونه \f3java\&.lang java\&.lang\&.reflect java\&.awt\fR\&. اگر می‌خواهید زیربسته‌ها را نیز مستندسازی کنید، از گزینهٔ \f3-subpackages\fR برای تعیین بسته‌ها استفاده کنید\&. به‌طور پیش‌فرض، \f3javadoc\fR بسته‌های مشخص‌شده را در دایرکتوری جاری و زیردایرکتوری‌های آن جستجو می‌کند\&. از گزینهٔ \f3-sourcepath\fR برای تعیین فهرست دایرکتوری‌هایی که بسته‌ها در آن‌ها جستجو شوند استفاده نمایید\&. .TP \fIsource-files\fR نام فایل‌های منبع Java که می‌خواهید مستندسازی کنید، جدا شده با فاصله، برای نمونه \f3Class\&.java Object\&.java Button\&.java\fR\&. به‌طور پیش‌فرض، \f3javadoc\fR کلاس‌های مشخص‌شده را در دایرکتوری جاری جستجو می‌کند\&. با این حال، می‌توانید مسیر کامل به فایل کلاس را مشخص کرده و از نویسه‌های عام (wildcard) استفاده کنید، برای نمونه \f3/home/src/java/awt/Graphics*\&.java\fR\&. همچنین می‌توانید مسیر را به‌صورت نسبی نسبت به دایرکتوری جاری تعیین نمایید\&. .TP \fIoptions\fR گزینه‌های خط فرمان، جدا شده با فاصله\&. بخش گزینه‌ها (Options) را ببینید\&. .TP \fI@argfiles\fR نام فایل‌هایی که فهرستی از گزینه‌های دستور \f3javadoc\fR، نام بسته‌ها و نام فایل‌های منبع را به هر ترتیبی در بر دارند\&. .SH "توضیحات (DESCRIPTION)" دستور \f3javadoc\fR اعلان‌ها و کامنت‌های مستندسازی را در مجموعه‌ای از فایل‌های منبع Java تجزیه کرده و مجموعه‌ای متناظر از صفحات HTML تولید می‌کند که (به‌طور پیش‌فرض) کلاس‌های public و protected، کلاس‌های تودرتو (اما نه کلاس‌های داخلی ناشناس)، رابط‌ها (interfaces)، سازنده‌ها (constructors)، متدها (methods) و فیلدها (fields) را توصیف می‌کنند\&. می‌توانید از دستور \f3javadoc\fR برای تولید مستندات API یا مستندات پیاده‌سازی برای مجموعه‌ای از فایل‌های منبع استفاده کنید\&. .PP می‌توانید دستور \f3javadoc\fR را روی بسته‌های کامل، فایل‌های منبع منفرد، یا هر دو اجرا کنید\&. هنگام مستندسازی بسته‌های کامل، می‌توانید یا از گزینهٔ \f3-subpackages\fR برای پیمایش بازگشتی یک دایرکتوری و زیردایرکتوری‌های آن استفاده کنید، یا فهرستی صریح از نام‌های بسته را ارسال نمایید\&. هنگامی که فایل‌های منبع منفرد را مستندسازی می‌کنید، فهرستی از نام‌های فایل‌های منبع Java را ارسال کنید\&. بخش مثال‌های ساده (Simple Examples) را ببینید\&. .SS "پردازش فایل‌های منبع (PROCESS SOURCE FILES)" دستور \f3javadoc\fR فایل‌هایی را که پسوند منبع دارند و سایر فایل‌های شرح داده‌شده در بخش فایل‌های منبع (Source Files) پردازش می‌کند\&. اگر دستور \f3javadoc\fR را با ارسال نام‌های منفرد فایل‌های منبع اجرا کنید، می‌توانید دقیقاً تعیین کنید که کدام فایل‌های منبع پردازش شوند\&. با این حال، بیشتر توسعه‌دهندگان بدین صورت کار نمی‌کنند، زیرا ارسال نام بسته‌ها ساده‌تر است\&. دستور \f3javadoc\fR می‌تواند بدون تعیین صریح نام فایل‌های منبع به سه روش اجرا شود: می‌توانید نام بسته‌ها را ارسال کنید، از گزینهٔ \f3-subpackages\fR استفاده نمایید، یا از نویسه‌های عام (wildcards) همراه با نام فایل‌های منبع بهره ببرید\&. در این موارد، دستور \f3javadoc\fR تنها در صورتی یک فایل منبع را پردازش می‌کند که فایل تمام شرایط زیر را برآورده سازد: .TP 0.2i \(bu پیشوند نام فایل (با حذف \f3\&.java\fR) یک نام کلاس معتبر باشد\&. .TP 0.2i \(bu نام مسیر نسبت به ریشهٔ درخت منبع، پس از تبدیل جداکننده‌ها به نقطه، یک نام بستهٔ معتبر باشد\&. .TP 0.2i \(bu عبارت \f3package\fR حاوی نام بستهٔ معتبر باشد\&. .PP پردازش پیوندها (Processing Links) در حین یک اجرا، دستور \f3javadoc\fR پیوندهای ارجاع‌متقاطع (cross-reference) را به نام‌های بسته، کلاس و عضوی که بخشی از آن اجرا هستند اضافه می‌کند\&. پیوندها در مکان‌های زیر ظاهر می‌شوند\&. برای شرح برچسب‌های @، بخش برچسب‌های Javadoc (Javadoc Tags) را ببینید\&. .TP 0.2i \(bu اعلان‌ها (انواع بازگشتی، انواع آرگومان‌ها، و انواع فیلدها)\&. .TP 0.2i \(bu بخش‌های \fIهمچنین ببینید (See Also)\fR که از برچسب‌های \f3@see\fR تولید شده‌اند\&. .TP 0.2i \(bu متن درون‌خطی تولید شده از برچسب‌های \f3{@link}\fR\&. .TP 0.2i \(bu نام استثناها که از برچسب‌های \f3@throws\fR تولید شده‌اند\&. .TP 0.2i \(bu پیوندهای \fISpecified by\fR به اعضای رابط و پیوندهای \fIOverrides\fR به اعضای کلاس\&. بخش Method Comment Inheritance را ببینید\&. .TP 0.2i \(bu جدول‌های خلاصه‌ای که بسته‌ها، کلاس‌ها و اعضا را فهرست می‌کنند\&. .TP 0.2i \(bu درخت‌های وراثت بسته و کلاس\&. .TP 0.2i \(bu نمایه (index)\&. .PP می‌توانید با استفاده از گزینه‌های \f3-link\fR و \f3-linkoffline\fR، پیوندهایی را به متن‌های موجود برای کلاس‌هایی که در خط فرمان گنجانده نشده‌اند (اما به‌طور جداگانه تولید شده‌اند) بیفزایید\&. .PP جزئیات پردازش (Processing Details) دستور \f3javadoc\fR در هر بار اجرا یک سند کامل ایجاد می‌کند\&. این دستور ساخت افزایشی (incremental build) انجام نمی‌دهد که نتایج اجراهای پیشین را ویرایش کرده یا مستقیماً ادغام کند\&. با این حال، دستور \f3javadoc\fR می‌تواند به نتایج حاصل از سایر اجراها پیوند دهد\&. .PP پیاده‌سازی دستور \f3javadoc\fR به کامپایلر Java نیاز داشته و بر آن متکی است\&. دستور \f3javadoc\fR بخشی از دستور \f3javac\fR را فرامی‌خواند تا اعلان‌ها را کامپایل کرده و از پیاده‌سازی اعضا چشم‌پوشی کند\&. دستور \f3javadoc\fR یک بازنمایی درونی غنی از کلاس‌ها شامل سلسله‌مراتب کلاس‌ها و روابط استفاده می‌سازد تا HTML را تولید نماید\&. دستور \f3javadoc\fR همچنین مستندات ارائه‌شده توسط کاربر را از کامنت‌های مستندسازی در کد منبع استخراج می‌کند\&. بخش کامنت‌های مستندسازی (Documentation Comments) را ببینید\&. .PP دستور \f3javadoc\fR روی فایل‌های منبعی که فایل‌های ساختگیِ صرف (stub files) بدون بدنهٔ متد هستند نیز اجرا می‌شود\&. این بدان معناست که می‌توانید در مراحل اولیهٔ طراحی پیش از پیاده‌سازی API، کامنت‌های مستندسازی بنویسید و دستور \f3javadoc\fR را اجرا کنید\&. .PP اتکا به کامپایلر اطمینان می‌دهد که خروجی HTML دقیقاً با پیاده‌سازی واقعی مطابقت داشته باشد؛ پیاده‌سازی‌ای که ممکن است به‌جای کد منبع صریح، بر کدهای ضمنی متکی باشد\&. برای نمونه، دستور \f3javadoc\fR سازنده‌های پیش‌فرضی را که در فایل‌های کلاس کامپایل‌شده موجودند ولی در کد منبع وجود ندارند، مستندسازی می‌کند\&. .PP در بسیاری از موارد، دستور \f3javadoc\fR به شما اجازه می‌دهد تا برای فایل‌های منبع با کدهای ناقص یا دارای خطا نیز مستندات تولید کنید\&. می‌توانید پیش از اتمام تمام اشکال‌زدایی‌ها و عیب‌یابی‌ها، مستندات را ایجاد نمایید\&. دستور \f3javadoc\fR بررسی‌های اولیه‌ای روی کامنت‌های مستندسازی انجام می‌دهد\&. .PP هنگامی که دستور \f3javadoc\fR ساختار درونی خود را برای مستندسازی می‌سازد، تمام کلاس‌های ارجاع‌داده‌شده را بارگذاری می‌کند\&. به همین دلیل، دستور \f3javadoc\fR باید بتواند همهٔ کلاس‌های ارجاع‌شده را، اعم از کلاس‌های راه‌انداز (bootstrap classes)، افزونه‌ها (extensions)، یا کلاس‌های کاربر بیابد\&. به بخش How Classes Are Found در آدرس http://docs\&.oracle\&.com/javase/8/docs/technotes/tools/findingclasses\&.html مراجعه کنید\&. .PP به‌طور معمول، کلاس‌هایی که ایجاد می‌کنید باید یا به‌عنوان یک افزونه بارگذاری شوند یا در مسیر کلاس (class path) دستور \f3javadoc\fR قرار گیرند\&..SS "داکلت‌های JAVADOC (JAVADOC DOCLETS)" شما می‌توانید محتوا و قالب خروجی دستور \f3javadoc\fR را با داکلت‌ها سفارشی‌سازی کنید\&. دستور \f3javadoc\fR دارای یک داکلت درونی پیش‌فرض به نام داکلت استاندارد (standard doclet) است که مستندات API با قالب HTML تولید می‌کند\&. شما می‌توانید داکلت استاندارد را تغییر دهید، از آن زیرکلاس بسازید، یا داکلت اختصاصی خود را بنویسید تا خروجی‌هایی در قالب‌های HTML، XML، MIF، RTF یا هر قالب دلخواه دیگری تولید کند\&. .PP هنگامی که یک داکلت سفارشی با گزینه \f3-doclet\fR تعیین نشده باشد، دستور \f3javadoc\fR از داکلت استاندارد پیش‌فرض استفاده می‌کند\&. دستور \f3javadoc\fR دارای گزینه‌های متعددی است که صرف‌نظر از داکلتِ در حال استفاده، در دسترس هستند\&. داکلت استاندارد مجموعه‌ای تکمیلی از گزینه‌های خط فرمان را ارائه می‌دهد\&. بخش گزینه‌ها (Options) را ببینید\&. .SH "فایل‌های منبع (SOURCE FILES)" دستور \f3javadoc\fR خروجی‌هایی تولید می‌کند که از انواع فایل‌های منبع زیر سرچشمه می‌گیرند: فایل‌های منبع زبان جاوا برای کلاس‌ها (\f3\&.java\fR)، فایل‌های توضیحات بسته، فایل‌های توضیحات کلی (overview)، و فایل‌های پردازش‌نشده گوناگون\&. این بخش همچنین فایل‌های آزمون و فایل‌های الگو را شرح می‌دهد که ممکن است در درخت منبع وجود داشته باشند، اما می‌خواهید مطمئن شوید که مستندسازی نمی‌شوند\&. .SS "فایل‌های منبع کلاس (CLASS SOURCE FILES)" هر کلاس یا رابط (interface) و اعضای آن می‌توانند توضیحات مستندسازی مربوط به خود را در یک فایل منبع داشته باشند\&. بخش Documentation Comments را ببینید\&. .SS "فایل‌های توضیحات بسته (PACKAGE COMMENT FILES)" هر بسته می‌تواند توضیحات مستندسازی مربوط به خود را در فایل منبع اختصاصی‌اش داشته باشد که دستور \f3javadoc\fR آن را در صفحه خلاصه بسته (package summary) ادغام می‌کند\&. شما معمولاً هر مستنداتی را که برای کل بسته اعمال می‌شود در این توضیحات قرار می‌دهید\&. .PP برای ایجاد یک فایل توضیحات بسته، می‌توانید توضیحات خود را در یکی از فایل‌های زیر قرار دهید: .TP 0.2i \(bu فایل \f3package-info\&.java\fR می‌تواند شامل اعلان بسته، حاشیه‌نویسی‌های بسته (package annotations)، توضیحات بسته و برچسب‌های Javadoc باشد\&. استفاده از این فایل ترجیح داده می‌شود\&. .TP 0.2i \(bu فایل \f3package\&.html\fR تنها شامل توضیحات بسته و برچسب‌های Javadoc است و حاشیه‌نویسی‌های بسته را نمی‌پذیرد\&. .PP یک بسته می‌تواند یک فایل \f3package\&.html\fR تکی یا یک فایل \f3package-info\&.java\fR تکی داشته باشد، اما نباید شامل هر دوی آن‌ها باشد\&. هر یک از این فایل‌ها را در دایرکتوری بسته در درخت منبع و در کنار فایل‌های منبع خود قرار دهید\&. .PP فایل package-info\&.java فایل \f3package-info\&.java\fR می‌تواند شامل توضیح بسته‌ای با ساختار زیر باشد\&. این توضیح پیش از اعلان بسته قرار می‌گیرد\&. .PP \fIنکته:\fR جداکننده‌های توضیح \f3/**\fR و \f3*/\fR باید وجود داشته باشند، اما می‌توان از ستاره‌های ابتدای خطوط میانی صرف‌نظر کرد\&. .sp .nf \f3/**\fP .fi .nf \f3 * Provides the classes necessary to create an \fP .fi .nf \f3 * applet and the classes an applet uses \fP .fi .nf \f3 * to communicate with its applet context\&.\fP .fi .nf \f3 *

\fP .fi .nf \f3 * The applet framework involves two entities:\fP .fi .nf \f3 * the applet and the applet context\&.\fP .fi .nf \f3 * An applet is an embeddable window (see the\fP .fi .nf \f3 * {@link java\&.awt\&.Panel} class) with a few extra\fP .fi .nf \f3 * methods that the applet context can use to \fP .fi .nf \f3 * initialize, start, and stop the applet\&.\fP .fi .nf \f3 *\fP .fi .nf \f3 * @since 1\&.0\fP .fi .nf \f3 * @see java\&.awt\fP .fi .nf \f3 */\fP .fi .nf \f3package java\&.lang\&.applet;\fP .fi .nf \f3\fP .fi .sp .PP فایل package\&.html فایل \f3package\&.html\fR می‌تواند شامل توضیح بسته‌ای با ساختار زیر باشد\&. این توضیح در عنصر \f3\fR قرار می‌گیرد\&. .PP فایل: \f3java/applet/package\&.html\fR .sp .nf \f3\fP .fi .nf \f3\fP .fi .nf \f3Provides the classes necessary to create an applet and the \fP .fi .nf \f3classes an applet uses to communicate with its applet context\&.\fP .fi .nf \f3

\fP .fi .nf \f3The applet framework involves two entities: the applet\fP .fi .nf \f3and the applet context\&. An applet is an embeddable\fP .fi .nf \f3window (see the {@link java\&.awt\&.Panel} class) with a\fP .fi .nf \f3few extra methods that the applet context can use to\fP .fi .nf \f3initialize, start, and stop the applet\&. \fP .fi .nf \f3\fP .fi .nf \f3@since 1\&.0 \fP .fi .nf \f3@see java\&.awt\fP .fi .nf \f3\fP .fi .nf \f3\fP .fi .nf \f3\fP .fi .sp فایل \f3package\&.html\fR یک فایل استاندارد HTML است و شامل اعلان بسته نمی‌شود\&. محتوای این فایل توضیحات، به استثنای یک مورد، به زبان HTML نوشته می‌شود\&. در توضیحات مستندسازی نباید از جداکننده‌های توضیح \f3/**\fR و \f3*/\fR یا ستاره‌های ابتدای خط استفاده شود\&. هنگام نوشتن این توضیحات، نخستین جمله را خلاصه‌ای درباره بسته قرار دهید و از گذاشتن عنوان یا هر متن دیگری میان تگ \f3\fR و نخستین جمله خودداری کنید\&. می‌توانید برچسب‌های بسته را درج کنید\&. تمام برچسب‌های بلوکی (block tags) باید پس از توضیحات اصلی قرار گیرند\&. اگر یک برچسب \f3@see\fR در فایل توضیحات بسته اضافه می‌کنید، باید نام کاملاً مشخص (fully qualified name) داشته باشد\&. .PP پردازش فایل توضیحات هنگامی که دستور \f3javadoc\fR اجرا می‌شود، به دنبال فایل توضیحات بسته می‌گردد\&. در صورت یافتن فایل توضیحات بسته، دستور \f3javadoc\fR مراحل زیر را انجام می‌دهد: .TP 0.2i \(bu توضیحات را جهت پردازش کپی می‌کند\&. برای package\&.html، دستور \f3javadoc\fR تمام محتوای میان تگ‌های HTML \f3\fR و \f3\fR را کپی می‌کند\&. می‌توانید بخش \f3\fR را برای درج تگ \f3\fR، بیانیه حق نشر فایل منبع، یا اطلاعات دیگر اضافه کنید؛ با این حال، هیچ‌کدام از این موارد در مستندات تولیدشده نمایش داده نخواهند شد\&. .TP 0.2i \(bu برچسب‌های بسته را پردازش می‌کند\&. بخش Package Tags را ببینید\&. .TP 0.2i \(bu متن پردازش‌شده را در پایین صفحه خلاصه بسته درج می‌کند\&. بخش Java Platform, Standard Edition API Specification Overview را در http://docs\&.oracle\&.com/javase/8/docs/api/overview-summary\&.html ببینید\&. .TP 0.2i \(bu نخستین جمله توضیحات بسته را به بالای صفحه خلاصه بسته کپی می‌کند\&. دستور \f3javadoc\fR همچنین نام بسته و این نخستین جمله را به فهرست بسته‌ها در صفحه نمای کلی (overview) اضافه می‌کند\&. بخش Java Platform, Standard Edition API Specification Overview را در http://docs\&.oracle\&.com/javase/8/docs/api/overview-summary\&.html ببینید\&. پایان جمله بر اساس همان قواعدی تعیین می‌شود که برای تشخیص پایان جمله نخست توضیحات اصلی کلاس و عضو به کار می‌روند\&..SS "فایلهای توضیحات مرور کلی (OVERVIEW COMMENT FILES)" هر برنامه یا مجموعه‌ای از بسته‌ها که مستندسازی می‌کنید می‌تواند کامنت توضیحات مرور کلی (overview) مختص به خود را داشته باشد که در فایل مبدأ جداگانه‌ای نگهداری می‌شود و دستور \f3javadoc\fR آن را در صفحهٔ مرور کلیِ تولیدشده ادغام می‌کند\&. معمولاً در این کامنت هرگونه مستنداتی را قرار می‌دهید که برای کل برنامه یا مجموعهٔ بسته‌ها اعمال می‌شود\&. .PP می‌توانید هر نامی که می‌خواهید، مانند overview\&.html، برای این فایل انتخاب کرده و آن را در هر جایی قرار دهید\&. یک مکان متداول در بالاترین سطح درخت سورس است\&. .PP به‌عنوان مثال، اگر فایلهای سورس بستهٔ \f3java\&.applet\fR در دایرکتوری /home/user/src/java/applet قرار داشته باشند، می‌توانید یک فایل کامنت مرور کلی در /home/user/src/overview\&.html بسازید\&. .PP می‌توانید برای همان مجموعه فایلهای سورس، چندین فایل کامنت مرور کلی داشته باشید، در صورتی که بخواهید دستور \f3javadoc\fR را چندین بار بر روی مجموعه‌های متفاوتی از بسته‌ها اجرا کنید\&. برای مثال، می‌توانید دستور \f3javadoc\fR را یک بار با گزینهٔ \f3-private\fR برای مستندات داخلی و بار دیگر بدون این گزینه برای مستندات عمومی اجرا کنید\&. در این حالت، می‌توانید در جملهٔ نخست هر فایل کامنت مرور کلی، مستندات را به‌صورت عمومی یا داخلی توصیف کنید\&. .PP محتوای فایل کامنت مرور کلی، یک کامنت مستندات بزرگ است که با HTML نوشته شده است\&. جملهٔ نخست را خلاصه‌ای دربارهٔ برنامه یا مجموعهٔ بسته‌ها قرار دهید\&. بین تگ \f3<body>\fR و جملهٔ نخست، هیچ عنوان یا متن دیگری قرار ندهید\&. تمام تگ‌ها به‌جز تگ‌های درون‌خطی، مانند تگ {\f3@link}\fR، باید پس از توضیحات اصلی بیایند\&. اگر یک تگ \f3@see\fR اضافه می‌کنید، باید دارای یک نام کاملاً مشخص (fully qualified name) باشد\&. .PP هنگام اجرای دستور \f3javadoc\fR، نام فایل کامنت مرور کلی را با گزینهٔ \f3-overview\fR مشخص کنید\&. سپس فایل به‌شیوه‌ای مشابه با فایل کامنت بسته پردازش می‌شود\&. دستور \f3javadoc\fR کارهای زیر را انجام می‌دهد: .TP 0.2i \(bu تمامی محتوای بین تگ‌های \f3<body>\fR و \f3</body>\fR را برای پردازش کپی می‌کند\&. .TP 0.2i \(bu تگ‌های مرور کلی موجود را پردازش می‌کند\&. بخش Overview Tags را ببینید\&. .TP 0.2i \(bu متن پردازش‌شده را در انتهای صفحهٔ مرور کلیِ تولیدشده درج می‌کند\&. بخش Java Platform Standard Edition API Specification Overview را در http://docs\&.oracle\&.com/javase/8/docs/api/overview-summary\&.html ببینید .TP 0.2i \(bu جملهٔ نخست کامنت مرور کلی را در بالای صفحهٔ خلاصه مرور کلی کپی می‌کند\&. .SS "فایلهای پردازشنشده (UNPROCESSED FILES)" فایلهای سورس شما می‌توانند شامل هر فایلی باشند که می‌خواهید دستور \f3javadoc\fR آنها را در دایرکتوری مقصد کپی کند\&. این فایلها معمولاً شامل فایلهای گرافیکی، فایلهای سورس و class نمونهٔ جاوا، و فایلهای HTML مستقلی هستند که محتوای زیاد آنها ممکن است کامنت مستندات یک فایل سورس جاوای معمولی را بیش از حد شلوغ کند\&. .PP برای گنجاندن فایلهای پردازشنشده، آنها را در دایرکتوری‌ای به نام doc-files قرار دهید\&. دایرکتوری doc-files می‌تواند یک زیردایرکتوری از هر دایرکتوری بسته‌ای باشد که شامل فایلهای سورس است\&. شما می‌توانید برای هر بسته یک زیردایرکتوری doc-files داشته باشید\&. .PP برای مثال، اگر می‌خواهید تصویر یک دکمه را در مستندات کلاس \f3java\&.awt\&.Button\fR بگنجانید، فایل تصویر را در دایرکتوری /home/user/src/java/awt/doc-files/ قرار دهید\&. دایرکتوری doc-files را در /home/user/src/java/doc-files قرار ندهید، زیرا java یک بسته نیست و هیچ فایل سورسی در بر ندارد\&. .PP تمام پیوندها به فایلهای پردازشنشده باید در کد گنجانده شوند زیرا دستور \f3javadoc\fR به این فایلها نگاه نمی‌کند\&. دستور \f3javadoc\fR این دایرکتوری و تمام محتویات آن را در مقصد کپی می‌کند\&. مثال زیر نشان می‌دهد که پیوند در کامنت مستندات Button\&.java چگونه ممکن است باشد: .sp .nf \f3/**\fP .fi .nf \f3 * This button looks like this: \fP .fi .nf \f3 * <img src="doc\-files/Button\&.gif">\fP .fi .nf \f3 */\fP .fi .nf \f3\fP .fi .sp .SS "فایلهای آزمون و الگو (TEST AND TEMPLATE FILES)" می‌توانید فایلهای آزمون و الگو را در درخت سورس، در همان دایرکتوری یا در زیردایرکتوری‌ای از دایرکتوری قرارگیری فایلهای سورس ذخیره کنید\&. برای جلوگیری از پردازش فایلهای آزمون و الگو، دستور \f3javadoc\fR را اجرا کرده و نام‌های تک‌تک فایلهای سورس را صراحتاً به آن ارسال کنید\&. .PP فایلهای آزمون، فایلهای سورس معتبر و قابل کامپایل هستند\&. فایلهای الگو فایلهای سورس معتبر و سازگار نیستند، اما اغلب پسوند \f3\&.java\fR دارند\&. .PP فایلهای آزمون (Test Files) اگر می‌خواهید فایلهای آزمون شما به یک بستهٔ بدون نام یا به بسته‌ای غیر از بستهٔ فایلهای سورس تعلق داشته باشند، فایلهای آزمون را در یک زیردایرکتوری در زیر فایلهای سورس قرار دهید و یک نام نامعتبر به آن دایرکتوری اختصاص دهید\&. اگر فایلهای آزمون را در همان دایرکتوریِ سورس قرار دهید و دستور \f3javadoc\fR را با یک آرگومان خط فرمان که نشان‌دهندهٔ نام بسته است فراخوانی کنید، فایلهای آزمون موجب هشدار یا خطا می‌شوند\&. اگر فایلها در زیردایرکتوری با نام نامعتبر باشند، دایرکتوری فایلهای آزمون نادیده گرفته شده و هیچ خطا یا هشداری صادر نمی‌شود\&. برای مثال، برای افزودن فایلهای آزمون برای فایلهای سورس در com\&.package1، آنها را در زیردایرکتوری‌ای با یک نام بستهٔ نامعتبر قرار دهید\&. نام دایرکتوری زیر نامعتبر است زیرا حاوی خط پیوند (hyphen) می‌باشد: .sp .nf \f3com/package1/test\-files/\fP .fi .nf \f3\fP .fi .sp اگر فایلهای آزمون شما حاوی کامنت‌های مستندات هستند، می‌توانید یک اجرای جداگانه از دستور \f3javadoc\fR را با ارسال نام‌های فایلهای سورس آزمون با استفاده از نویسه‌های عمومی (wildcards)، مانند \f3com/package1/test-files/*\&.java\fR، برای تولید مستندات فایلهای آزمون برپا کنید\&. .PP فایلهای الگو (Template Files) اگر می‌خواهید یک فایل الگو در دایرکتوری سورس باشد، اما هنگام اجرای دستور \f3javadoc\fR خطایی تولید نکند، یک نام فایل نامعتبر مانند \f3Buffer-Template\&.java\fR به آن بدهید تا از پردازش آن جلوگیری شود\&. دستور \f3javadoc\fR تنها فایلهای سورسی را پردازش می‌کند که نام آنها پس از حذف پسوند \f3\&.java\fR، یک نام کلاس معتبر باشد\&. .SH "فایلهای تولیدشده (GENERATED FILES)" به‌طور پیش‌فرض، دستور \f3javadoc\fR از یک doclet استاندارد استفاده می‌کند که مستنداتی با قالب‌بندی HTML تولید می‌کند\&. این doclet استاندارد، صفحه‌های محتوای اصلی، ارجاع متقابل، و صفحه‌های پشتیبانی شرح داده‌شده در اینجا را تولید می‌کند\&. هر صفحهٔ HTML با یک فایل جداگانه متناظر است\&. دستور \f3javadoc\fR دو نوع فایل تولید می‌کند\&. نوع اول بر اساس کلاس‌ها و رابط‌ها نام‌گذاری می‌شود\&. نوع دوم حاوی خط پیوند است (مانند package-summary\&.html) تا از تداخل با نوع اول فایلها جلوگیری شود\&. .SS "صفحه‌های محتوای اصلی (BASIC CONTENT PAGES)" .TP 0.2i \(bu یک صفحهٔ کلاس یا رابط (classname\&.html) برای هر کلاس یا رابطی که مستندسازی می‌شود\&. .TP 0.2i \(bu یک صفحهٔ بسته (package-summary\&.html) برای هر بسته‌ای که مستندسازی می‌شود\&. دستور \f3javadoc\fR هر متن HTML ارائه‌شده در فایلی به نام package\&.html یا package-info\&.java در دایرکتوری بسته در درخت سورس را در بر می‌گیرد\&. .TP 0.2i \(bu یک صفحهٔ مرور کلی (overview-summary\&.html) برای کل مجموعهٔ بسته‌ها\&. صفحهٔ مرور کلی صفحهٔ نخست مستندات تولیدشده است\&. دستور \f3javadoc\fR هر متن HTML ارائه‌شده در فایلی را که توسط گزینهٔ \f3-overview\fR مشخص شده در بر می‌گیرد\&. صفحهٔ Overview تنها زمانی ایجاد می‌شود که دو یا چند نام بسته را به دستور \f3javadoc\fR بدهید\&. بخش‌های HTML Frames و گزینه‌ها (Options) را ببینید\&. .SS "صفحه‌های ارجاع متقابل (CROSS-REFERENCE PAGES)" .TP 0.2i \(bu یک صفحهٔ سلسله‌مراتب کلاس برای کل مجموعهٔ بسته‌ها (overview-tree\&.html)\&. برای مشاهدهٔ صفحهٔ سلسله‌مراتب، روی \fIOverview\fR در نوار ناوبری و سپس روی \fITree\fR کلیک کنید\&. .TP 0.2i \(bu یک صفحهٔ سلسله‌مراتب کلاس برای هر بسته (package-tree\&.html)\&. برای مشاهدهٔ صفحهٔ سلسله‌مراتب، به صفحهٔ یک بسته، کلاس یا رابط خاص بروید و برای نمایش سلسله‌مراتب آن بسته، روی \fITree\fR کلیک کنید\&. .TP 0.2i \(bu یک صفحهٔ استفاده برای هر بسته (package-use\&.html) و یک صفحهٔ استفادهٔ مجزا برای هر کلاس و رابط (class-use/classname\&.html)\&. صفحهٔ استفاده شرح می‌دهد که چه بسته‌ها، کلاس‌ها، متدها، سازنده‌ها و فیلدهایی از هر بخش از کلاس، رابط یا بستهٔ مشخص‌شده استفاده می‌کنند\&. برای مثال، با فرض یک کلاس یا رابط A، صفحهٔ استفادهٔ آن شامل زیرکلاس‌های A، فیلدهای اعلان‌شده به‌صورت A، متدهایی که A برمی‌گردانند، و متدها و سازندگانی با پارامترهایی از نوع A است\&. برای مشاهدهٔ صفحهٔ استفاده، به بسته، کلاس یا رابط رفته و روی پیوند \fIUse\fR در نوار ناوبری کلیک کنید\&. .TP 0.2i \(bu یک صفحهٔ API منسوخ‌شده (deprecated-list\&.html) که تمام APIهای منسوخ‌شده و جایگزین‌های پیشنهادی آنها را فهرست می‌کند\&. از APIهای منسوخ‌شده اجتناب کنید زیرا ممکن است در پیاده‌سازی‌های آینده حذف شوند\&. .TP 0.2i \(bu یک صفحهٔ مقادیر فیلدهای ثابت (constant-values\&.html) برای مقادیر فیلدهای استاتیک\&. .TP 0.2i \(bu یک صفحهٔ فرم سریال‌سازی‌شده (serialized-form\&.html) که اطلاعاتی دربارهٔ کلاس‌های قابل سریال‌سازی و قابل برون‌ریزی به همراه شرح فیلدها و متدها ارائه می‌دهد\&. اطلاعات این صفحه برای پیاده‌سازان مجدد کاربرد دارد و نه برای توسعه‌دهندگانی که می‌خواهند از API استفاده کنند\&. برای دسترسی به صفحهٔ فرم سریال‌سازی‌شده، به هر کلاس سریال‌سازی‌شده بروید و در بخش See Also کامنت کلاس، روی \fISerialized Form\fR کلیک کنید\&. doclet استاندارد یک صفحهٔ فرم سریال‌سازی‌شده تولید می‌کند که هر کلاسی (عمومی یا غیرعمومی) را که Serializable را به همراه متدهای \f3readObject\fR و \f3writeObject\fR آن، فیلدهایی که سریال‌سازی می‌شوند، و کامنت‌های مستندات ناشی از تگ‌های \f3@serial\fR، \f3@serialField\fR، و \f3@serialData\fR پیاده‌سازی کرده است فهرست می‌کند\&. کلاس‌های سریال‌پذیر عمومی را می‌توان با علامت‌گذاری آنها (یا بستهٔ آنها) با \f3@serial\fR exclude مستثنی کرد، و کلاس‌های سریال‌پذیر با سطح دسترسی بسته را می‌توان با علامت‌گذاری آنها (یا بستهٔ آنها) با یک \f3@serial\fR include گنجاند\&. از نگارش 1\&.4 به بعد، می‌توانید فرم کامل سریال‌سازی‌شده را برای کلاس‌های عمومی و خصوصی با اجرای دستور \f3javadoc\fR بدون مشخص کردن گزینهٔ \f3-private\fR تولید کنید\&. بخش گزینه‌ها (Options) را ببینید\&. .TP 0.2i \(bu یک صفحهٔ نمایه (\f3index-*\&.html\fR) از تمام نام‌های کلاس‌ها، رابط‌ها، سازنده‌ها، فیلدها و متدها، به ترتیب حروف الفبا\&. صفحهٔ نمایه برای یونیکد بین‌المللی‌سازی شده است و می‌تواند به‌عنوان یک فایل واحد یا به‌عنوان یک فایل جداگانه برای هر نویسهٔ آغازین (مانند A\(enZ برای انگلیسی) تولید شود\&. .SS "صفحه‌های پشتیبانی (SUPPORT PAGES)" .TP 0.2i \(bu یک صفحهٔ راهنما (help-doc\&.html) که نوار ناوبری و صفحه‌های قبلی را شرح می‌دهد\&. از \f3-helpfile\fR برای بازنویسی فایل راهنمای پیش‌فرض با فایل راهنمای سفارشی خود استفاده کنید\&. .TP 0.2i \(bu یک فایل index\&.html که فریم‌های HTML را برای نمایش ایجاد می‌کند\&. این فایل را برای نمایش صفحهٔ نخست همراه با فریم‌ها بارگذاری کنید\&. فایل index\&.html هیچ محتوای متنی ندارد\&. .TP 0.2i \(bu چندین فایل فریم (\f3*-frame\&.html\fR) که حاوی فهرست‌هایی از بسته‌ها، کلاس‌ها و رابط‌ها هستند\&. فایلهای فریم، فریم‌های HTML را نمایش می‌دهند\&. .TP 0.2i \(bu یک فایل فهرست بسته (package-list) که توسط گزینه‌های \f3-link\fR و \f3-linkoffline\fR استفاده می‌شود\&. فایل فهرست بسته یک فایل متنی است که از طریق پیوندها قابل دسترسی نیست\&. .TP 0.2i \(bu یک فایل برگه‌سبک (stylesheet\&.css) که مقدار محدودی از رنگ، خانوادهٔ قلم، اندازهٔ قلم، سبک قلم و اطلاعات جای‌گیری در صفحه‌های تولیدشده را کنترل می‌کند\&. .TP 0.2i \(bu یک دایرکتوری doc-files که فایلهای تصویری، نمونه، کد منبع یا دیگر فایلهایی را که می‌خواهید در دایرکتوری مقصد کپی شوند نگهداری می‌کند\&. این فایلها توسط دستور \f3javadoc\fR پردازش نمی‌شوند\&. این دایرکتوری پردازش نمی‌شود مگر اینکه در درخت سورس وجود داشته باشد\&. .PP بخش گزینه‌ها (Options) را ببینید\&..SS "فریم‌های HTML (HTML FRAMES)" دستور \f3javadoc\fR بر اساس مقادیر ارائه‌شده به آن، حداقل تعداد فریم‌های ضروری (دو یا سه) را تولید می‌کند\&. هنگامی که تنها یک نام بسته یا فایل‌های منبع متعلق به یک بسته واحد را به عنوان آرگومان به دستور \f3javadoc\fR می‌دهید، این دستور از فهرست بسته‌ها صرف‌نظر می‌کند\&. در عوض، دستور \f3javadoc\fR یک فریم در ستون سمت چپ ایجاد می‌کند که فهرست کلاس‌ها را نمایش می‌دهد\&. هنگامی که دو یا چند نام بسته را ارسال می‌کنید، دستور \f3javadoc\fR فریم سومی ایجاد می‌کند که همه بسته‌ها و یک صفحه مرور کلی (overview-summary\&.html) را فهرست می‌کند\&. برای گذر از فریم‌ها، روی پیوند \fINo Frames\fR کلیک کنید یا از صفحه overview-summary\&.html وارد مجموعه صفحات شوید\&. .SS "ساختار فایل‌های تولیدشده (GENERATED FILE STRUCTURE)" فایل‌های کلاس و رابط (interface) تولیدشده در همان سلسله‌مراتب پوشه‌ای سازمان‌دهی می‌شوند که فایل‌های منبع و فایل‌های کلاس جاوا سازمان‌دهی شده‌اند\&. این ساختار شامل یک پوشه به ازای هر زیربسته (subpackage) است\&. .PP برای نمونه، سند تولیدشده برای کلاس \f3java\&.applet\&.Applet\fR در مسیر java/applet/Applet\&.html قرار خواهد گرفت\&. .PP ساختار فایل برای بسته \f3java\&.applet\fR با فرض اینکه نام پوشه مقصد \f3apidocs\fR باشد، در ادامه آمده است\&. تمام فایل‌هایی که شامل واژه \fIframe\fR هستند، همان‌طور که اشاره شده در فریم‌های بالا-چپ یا پایین-چپ ظاهر می‌شوند\&. تمام فایل‌های HTML دیگر در فریم سمت راست نمایش داده می‌شوند\&. .PP پوشه‌ها پررنگ (bold) هستند\&. علامت‌های ستاره (*) نشان‌دهنده فایل‌ها و پوشه‌هایی است که اگر آرگومان‌های ارائه‌شده به دستور \f3javadoc\fR به جای نام بسته‌ها، نام فایل‌های منبع باشند، حذف می‌شوند\&. هنگامی که آرگومان‌ها نام فایل‌های منبع باشند، یک فهرست بسته خالی ایجاد می‌شود\&. پوشه doc-files در مقصد ایجاد نمی‌شود مگر اینکه در درخت منبع وجود داشته باشد\&. به بخش Generated Files مراجعه کنید\&. .TP 0.2i \(bu \fIapidocs\fR: پوشه سطح بالا .RS .TP 0.2i \(bu index\&.html: صفحه اولیه که فریم‌های HTML را برپا می‌کند .TP 0.2i \(bu *overview-summary\&.html: فهرست بسته‌ها به همراه خلاصه‌ها .TP 0.2i \(bu overview-tree\&.html: سلسله‌مراتب کلاس‌ها برای همه بسته‌ها .TP 0.2i \(bu deprecated-list\&.html: رابط‌های برنامه‌نویسی (API) منسوخ‌شده برای همه بسته‌ها .TP 0.2i \(bu constant-values\&.html: مقادیر فیلدهای ایستا (static) برای همه بسته‌ها .TP 0.2i \(bu serialized-form\&.html: فرم‌های سریال‌سازی‌شده برای همه بسته‌ها .TP 0.2i \(bu *overview-frame\&.html: همه بسته‌ها برای نمایش در فریم بالا-چپ .TP 0.2i \(bu allclasses-frame\&.html: همه کلاس‌ها برای نمایش در فریم پایین-چپ .TP 0.2i \(bu help-doc\&.html: راهنما درباره سازمان‌دهی صفحات Javadoc .TP 0.2i \(bu index-all\&.html: نمایه پیش‌فرض ایجادشده بدون گزینه \f3-splitindex\fR .TP 0.2i \(bu \fIindex-files\fR: پوشه ایجادشده با گزینه \f3-splitindex\fR .RS .TP 0.2i \(bu index-<number>\&.html: فایل‌های نمایه ایجادشده با گزینه \f3-splitindex\fR .RE .TP 0.2i \(bu package-list: نام بسته‌ها برای تفکیک ارجاع‌های خارجی .TP 0.2i \(bu stylesheet\&.css: قلم‌ها، رنگ‌ها، موقعیت‌ها و موارد دیگر را تعریف می‌کند .RE .TP 0.2i \(bu \fIjava\fR: پوشه بسته .RS .TP 0.2i \(bu \fIapplet\fR: پوشه زیربسته .RS .TP 0.2i \(bu Applet\&.html: صفحه کلاس \f3Applet\fR .TP 0.2i \(bu AppletContext\&.html: رابط \f3AppletContext\fR .TP 0.2i \(bu AppletStub\&.html: رابط \f3AppletStub\fR .TP 0.2i \(bu AudioClip\&.html: رابط \f3AudioClip\fR .TP 0.2i \(bu package-summary\&.html: کلاس‌ها به همراه خلاصه‌ها .TP 0.2i \(bu package-frame\&.html: کلاس‌های بسته برای نمایش در فریم پایین-چپ .TP 0.2i \(bu package-tree\&.html: سلسله‌مراتب کلاس‌ها برای این بسته .TP 0.2i \(bu package-use\&.html: محل‌های استفاده از این بسته .TP 0.2i \(bu \fIdoc-files\fR: پوشه فایل‌های تصویر و مثال .TP 0.2i \(bu \fIclass-use\fR: محل فایل‌های تصویر و مثال - Applet\&.html: موارد استفاده از کلاس Applet - AppletContext\&.html: موارد استفاده از رابط \f3AppletContext\fR - AppletStub\&.html: موارد استفاده از رابط \f3AppletStub\fR - AudioClip\&.html: موارد استفاده از رابط \f3AudioClip\fR .RE .RE .TP 0.2i \(bu \fIsrc-html\fR: پوشه کد منبع .RS .TP 0.2i \(bu \fIjava\fR: پوشه بسته .RS .TP 0.2i \(bu \fIapplet\fR: پوشه زیربسته - Applet\&.html: کد منبع Applet - AppletContext\&.html: کد منبع \f3AppletContext\fR - AppletStub\&.html: کد منبع \f3AppletStub\fR - AudioClip\&.html: کد منبع \f3AudioClip\fR .RE .RE.SS "اعلان‌های تولیدشده‌ی API (GENERATED API DECLARATIONS)" دستور \f3javadoc\fR در ابتدای توضیحات هر کلاس، رابط (interface)، فیلد، سازنده (constructor) و متد، اعلانی برای آن قلمِ API تولید می‌کند\&. برای نمونه، اعلان کلاس \f3Boolean\fR عبارت است از: .sp .nf \f3public final class Boolean\fP .fi .nf \f3extends Object\fP .fi .nf \f3implements Serializable\fP .fi .nf \f3\fP .fi .sp اعلان متد \f3Boolean\&.valueOf\fR چنین است: .sp .nf \f3public static Boolean valueOf(String s)\fP .fi .nf \f3\fP .fi .sp دستور \f3javadoc\fR می‌تواند اصلاح‌کننده‌های \f3public\fR، \f3protected\fR، \f3private\fR، \f3abstract\fR، \f3final\fR، \f3static\fR، \f3transient\fR و \f3volatile\fR را شامل شود، اما \f3synchronized\fR یا \f3native\fR را در بر نمی‌گیرد\&. اصلاح‌کننده‌های \f3synchronized\fR و \f3native\fR جزئیات پیاده‌سازی محسوب شده و بخشی از مشخصات API به شمار نمی‌آیند\&. .PP به‌جای تکیه بر کلیدواژه‌ی \f3synchronized\fR، خودِ APIها باید معناشناسی همزمانی (concurrency semantics) خود را در توضیحات اصلی کامنت مستند سازند\&. برای نمونه، یک توضیح ممکن است چنین باشد: یک شیء شمارش (enumeration) واحد نمی‌تواند به‌طور همزمان توسط چندین رشته مورد استفاده قرار گیرد\&. این مستند نباید نحوه‌ی دستیابی به این معناشناسی را شرح دهد\&. به‌عنوان نمونه‌ای دیگر، در حالی که گزینه‌ی \f3Hashtable\fR باید thread-safe باشد، دلیلی وجود ندارد تصریح شود که این امر با همگام‌سازی تمامی متدهای برون‌ریزی‌شده‌ی آن حاصل شده است\&. بهتر است حق همگام‌سازی داخلی در سطح bucket برای دستیابی به همزمانی بیشتر محفوظ بماند\&. .SH "کامنت‌های مستندسازی (DOCUMENTATION COMMENTS)" این بخش، کامنت‌های کد منبع و وراثت کامنت‌ها را شرح می‌دهد\&. .SS "کامنت‌های کد منبع (SOURCE CODE COMMENTS)" می‌توانید کامنت‌های مستندسازی را در کد منبع، پیش از اعلان‌های هر کلاس، رابط، متد، سازنده یا فیلد قرار دهید\&. همچنین می‌توانید کامنت‌های مستندسازی را برای هر بسته (package) و یک مورد دیگر را برای نمای کلی (overview) ایجاد کنید، هرچند ساختار دستوری (syntax) آن‌ها کمی متفاوت است\&. یک کامنت مستندسازی از نویسه‌های میان \f3/**\fR و \f3*/\fR پایانی تشکیل می‌شود\&. ستاره‌های ابتدایی در هر خط مجاز هستند و در بخش بعدی بیشتر شرح داده شده‌اند\&. متن موجود در یک کامنت می‌تواند در چندین خط ادامه یابد\&. .sp .nf \f3/**\fP .fi .nf \f3 * This is the typical format of a simple documentation comment\fP .fi .nf \f3 * that spans two lines\&.\fP .fi .nf \f3 */\fP .fi .nf \f3\fP .fi .sp برای صرفه‌جویی در فضا می‌توانید یک کامنت را در یک خط قرار دهید: .sp .nf \f3/** This comment takes up only one line\&. */\fP .fi .nf \f3\fP .fi .sp .PP محل قرارگیری کامنت‌ها (Placement of Comments) کامنت‌های مستندسازی تنها زمانی شناسایی می‌شوند که بلافاصله پیش از اعلان‌های کلاس، رابط، سازنده، متد یا فیلد قرار گیرند\&. کامنت‌های مستندسازی قرار داده شده در بدنه‌ی یک متد نادیده گرفته می‌شوند\&. دستور \f3javadoc\fR برای هر عبارت اعلان، تنها یک کامنت مستندسازی را به رسمیت می‌شناسد\&. بخش Where Tags Can Be Used را ببینید\&. .PP یک اشتباه رایج، قرار دادن عبارت \f3import\fR بین کامنت کلاس و اعلان کلاس است\&. در این مکان عبارت \f3import\fR قرار ندهید زیرا دستور \f3javadoc\fR کامنت کلاس را نادیده می‌گیرد\&. .sp .nf \f3/**\fP .fi .nf \f3 * This is the class comment for the class Whatever\&.\fP .fi .nf \f3 */\fP .fi .nf \f3\fP .fi .nf \f3import com\&.example; // MISTAKE \- Important not to put import statement here\fP .fi .nf \f3\fP .fi .nf \f3public class Whatever{ }\fP .fi .nf \f3\fP .fi .sp .PP بخش‌های کامنت (Parts of Comments) یک کامنت مستندسازی دارای یک بخش توضیحات اصلی است که بخش تگ‌ها پس از آن می‌آید\&. توضیحات اصلی پس از جداکننده‌ی آغازین \f3/**\fR شروع شده و تا بخش تگ‌ها ادامه می‌یابد\&. بخش تگ‌ها با نخستین تگ بلوکی (block tag) آغاز می‌شود که توسط اولین نویسه‌ی \f3@\fR که خطی را آغاز کند مشخص می‌گردد (با صرف‌نظر از ستاره‌های ابتدایی، فاصله‌ها و جداکننده‌ی آغازین \f3/**\fR)\&. داشتن کامنتی که فقط دارای بخش تگ‌ها و فاقد توضیحات اصلی باشد ممکن است\&. پس از شروع بخش تگ‌ها، توضیحات اصلی نمی‌تواند ادامه یابد\&. آرگومان یک تگ می‌تواند در چندین خط گسترش یابد\&. تعداد تگ‌ها می‌تواند نامحدود باشد، و برخی از انواع تگ‌ها را می‌توان تکرار کرد در حالی که برخی دیگر غیرقابل تکرار هستند\&. برای نمونه، این تگ \f3@see\fR بخش تگ‌ها را آغاز می‌کند: .sp .nf \f3/**\fP .fi .nf \f3 * This sentence holds the main description for this documentation comment\&.\fP .fi .nf \f3 * @see java\&.lang\&.Object\fP .fi .nf \f3 */\fP .fi .nf \f3\fP .fi .sp .PP تگ‌های بلوکی و درون‌خطی (Block and inline Tags) یک تگ، کلیدواژه‌ای ویژه درون یک کامنت مستندسازی است که توسط دستور \f3javadoc\fR پردازش می‌شود\&. دو گونه تگ وجود دارد: تگ‌های بلوکی که به صورت تگ \f3@tag\fR ظاهر می‌شوند (همچنین با عنوان تگ‌های مستقل یا standalone شناخته می‌شوند)، و تگ‌های درون‌خطی (inline) که درون آکولادها به شکل تگ \f3{@tag}\fR قرار می‌گیرند\&. برای اینکه یک تگ بلوکی تفسیر شود، باید در ابتدای خط بیاید، با نادیده گرفتن ستاره‌های ابتدایی، فاصله‌ها و جداکننده (\f3/**\fR)\&. این بدان معناست که می‌توانید از نویسه‌ی \f3@\fR در جاهای دیگر متن استفاده کنید و به عنوان آغاز یک تگ تفسیر نخواهد شد\&. اگر می‌خواهید خطی را با نویسه‌ی \f3@\fR آغاز کنید و نمی‌خواهید به عنوان تگ تفسیر شود، از نهاد HTML با عنوان \f3@\fR استفاده کنید\&. هر تگ بلوکی دارای متنی مرتبط است که شامل هر متنی پس از تگ تا تگ بعدی یا انتهای کامنت مستندسازی می‌شود (بدون در بر گرفتن خود تگ بعدی)\&. این متن مرتبط می‌تواند در چندین خط گسترش یابد\&. یک تگ درون‌خطی در هر جایی که متن مجاز باشد، مجاز بوده و تفسیر می‌شود\&. مثال زیر شامل تگ بلوکی \f3@deprecated\fR و تگ درون‌خطی \f3{@link}\fR است\&. بخش Javadoc Tags را ببینید\&. .sp .nf \f3/**\fP .fi .nf \f3 * @deprecated As of JDK 1\&.1, replaced by {@link #setBounds(int,int,int,int)}\fP .fi .nf \f3 */\fP .fi .nf \f3\fP .fi .sp .PP نوشتن کامنت‌ها در HTML (Write Comments in HTML) متن باید در قالب HTML به همراه نهادهای HTML و برچسب‌های HTML نوشته شود\&. می‌توانید از هر نسخه‌ای از HTML که مرورگرتان پشتیبانی می‌کند استفاده کنید\&. داک‌لت (doclet) استاندارد در جاهای دیگر (خارج از کامنت‌های مستندسازی) کدی منطبق با HTML 3\&.2 به همراه شیوه‌نامه‌های آبشاری (CSS) و فریم‌ها تولید می‌کند\&. برای فایل‌های تولیدشده، به دلیل مجموعه‌فریم‌ها (frame sets)، نسخه HTML 4\&.0 ترجیح داده می‌شود\&. .PP برای نمونه، نهادها برای علامت کوچکتری (<) و علامت بزرگتری (>) باید به صورت \f3<\fR و \f3>\fR نوشته شوند\&. به‌طور مشابه، علامت امپرسند (&) باید به صورت \f3&\fR نوشته شود\&. برچسب توپر HTML یعنی \f3<b>\fR در مثال زیر نشان داده شده است\&. .sp .nf \f3/**\fP .fi .nf \f3 * This is a <b>doc</b> comment\&.\fP .fi .nf \f3 * @see java\&.lang\&.Object\fP .fi .nf \f3 */\fP .fi .nf \f3\fP .fi .sp .PP ستاره‌های ابتدایی (Leading Asterisks) هنگامی که دستور \f3javadoc\fR یک کامنت مستندسازی را تجزیه می‌کند، ستاره‌های ابتدایی (*) در هر خط دور ریخته می‌شوند و فاصله‌ها و تب‌های پیش از این ستاره‌های ابتدایی (*) نیز حذف می‌گردند\&. اگر ستاره‌ی ابتدایی را در یک خط حذف کنید، فاصله‌ی خالی ابتدایی دیگر حذف نمی‌شود؛ در نتیجه می‌توانید نمونه کدهای خود را مستقیماً درون یک برچسب \f3<PRE>\fR در کامنت مستندسازی قرار دهید در حالی که تورفتگی آن حفظ می‌شود\&. فاصله‌ها توسط مرورگرها نسبت به تب‌ها به شکلی یکدست‌تر تفسیر می‌شوند\&. تورفتگی نسبت به حاشیه‌ی چپ سنجیده می‌شود (نه نسبت به جداکننده‌ی \f3/**\fR یا برچسب \f3<PRE>\fR)\&. .PP جمله‌ی نخست (First Sentence) نخستین جمله‌ی هر کامنت مستندسازی باید یک جمله‌ی خلاصه‌ساز باشد که شامل شرحی مختصر اما کامل از موجودیت اعلان‌شده باشد\&. این جمله در اولین نقطه‌ای که پس از آن یک فاصله، تب یا پایان‌دهنده‌ی خط قرار گیرد، یا در نخستین تگ بلوکی پایان می‌یابد\&. دستور \f3javadoc\fR این جمله‌ی نخست را در خلاصه‌ی اعضا (member summary) در بالای صفحه‌ی HTML کپی می‌کند\&. .PP اعلان‌های چندفیلدی (Multiple-Field Declarations) پلتفرم جاوا امکان اعلان چند فیلد را در یک عبارت واحد به شما می‌دهد، اما این عبارت تنها می‌تواند یک کامنت مستندسازی داشته باشد که برای همه‌ی فیلدها کپی می‌شود\&. اگر برای هر فیلد کامنت‌های مستندسازی مجزا می‌خواهید، هر فیلد را در یک عبارت جداگانه اعلان کنید\&. برای نمونه، کامنت مستندسازی زیر اگر در قالب یک اعلان واحد نوشته شود منطقی نیست و بهتر است در قالب دو اعلان مدیریت شود: .sp .nf \f3/** \fP .fi .nf \f3 * The horizontal and vertical distances of point (x,y)\fP .fi .nf \f3 */\fP .fi .nf \f3public int x, y; // Avoid this \fP .fi .nf \f3\fP .fi .sp دستور \f3javadoc\fR مستندات زیر را از کد قبلی تولید می‌کند: .sp .nf \f3public int x\fP .fi .nf \f3\fP .fi .sp فاصله‌های افقی و عمودی نقطه‌ی (x, y)\&. .sp .nf \f3public int y\fP .fi .nf \f3\fP .fi .sp فاصله‌های افقی و عمودی نقطه‌ی (x, y)\&..PP استفاده از برچسب‌های سربرگ (Header Tags) هنگام نوشتن کامنت‌های مستندسازی برای اعضا، بهتر است از برچسب‌های سربرگ HTML مانند \f3<H1>\fR و \f3<H2>\fR استفاده نشود، زیرا دستور \f3javadoc\fR یک سند ساختاریافته کامل ایجاد می‌کند و این برچسب‌های ساختاری ممکن است با قالب‌بندی سند تولیدشده تداخل داشته باشند\&. با این حال، می‌توانید از این سربرگ‌ها در کامنت‌های کلاس و بسته (package) برای ایجاد ساختار مورد نظر خود استفاده کنید\&. .SS "وراثت کامنت متد (METHOD COMMENT INHERITANCE)" دستور \f3javadoc\fR اجازه وراثت کامنت متد را در کلاس‌ها و رابط‌ها (interfaces) می‌دهد تا متن‌های جاافتاده را پر کند یا به صورت صریح کامنت‌های متد را به ارث ببرد\&. سازنده‌ها (constructors)، فیلدها و کلاس‌های تو در تو (nested classes) کامنت‌های مستندسازی را به ارث نمی‌برند\&. .PP \fIنکته:\fR فایل منبع متدِ به ارث برده‌شده باید در مسیری که توسط گزینه \f3-sourcepath\fR مشخص شده است قرار داشته باشد تا کامنت مستندسازی آن برای کپی کردن در دسترس باشد\&. نه کلاس و نه بسته آن نیازی به ارسال از طریق خط فرمان ندارند\&. این رفتار برخلاف نسخه 1\&.3\&.\fIn\fR و نسخه‌های پیشین است که در آن‌ها کلاس حتماً باید یک کلاس مستندشده می‌بود\&. .PP پر کردن متن جاافتاده هنگامی که توضیحات اصلی، یا برچسب‌های \f3@return\fR، \f3@param\fR یا \f3@throws\fR در کامنت یک متد وجود نداشته باشند، دستور \f3javadoc\fR توضیحات اصلی یا کامنت برچسب متناظر را از متدی که آن را بازنویسی (override) یا پیاده‌سازی (implement) کرده است (در صورت وجود) کپی می‌کند\&. بخش «وراثت کامنت متد» (Method Comment Inheritance) را ببینید\&. .PP هنگامی که برچسب \f3@param\fR برای یک پارامتر خاص وجود ندارد، کامنت آن پارامتر از متد بالاتر در سلسله‌مراتب وراثت کپی می‌شود\&. هنگامی که برچسب \f3@throws\fR برای یک استثنای خاص وجود ندارد، برچسب \f3@throws\fR تنها در صورتی کپی می‌شود که آن استثنا اعلان شده باشد\&. .PP این رفتار برخلاف نسخه 1\&.3 و نسخه‌های پیشین است که در آن‌ها وجود هرگونه توضیحات اصلی یا برچسب مانع از به ارث رسیدن تمام کامنت‌ها می‌شد\&. .PP بخش «برچسب‌ها و گزینه‌های Javadoc» را ببینید\&. .PP وراثت صریح برچسب درون‌خطی \f3{@inheritDoc}\fR را در توضیحات اصلی متد یا کامنت برچسب‌های \f3@return\fR، \f3@param\fR یا \f3@throws\fR درج کنید\&. توضیحات اصلی یا کامنت برچسب به ارث رسیده متناظر در همان مکان کپی می‌شود\&. .SS "وراثت کلاس و رابط (CLASS AND INTERFACE INHERITANCE)" وراثت کامنت در تمام حالت‌های ممکنِ وراثت از کلاس‌ها و رابط‌ها رخ می‌دهد: .TP 0.2i \(bu هنگامی که یک متد در یک کلاس، متدی را در یک سوپرکلاس (superclass) بازنویسی (override) می‌کند .TP 0.2i \(bu هنگامی که یک متد در یک رابط، متدی را در یک رابط والد (superinterface) بازنویسی می‌کند .TP 0.2i \(bu هنگامی که یک متد در یک کلاس، متدی را در یک رابط پیاده‌سازی (implement) می‌کند .PP در دو حالت نخست، دستور \f3javadoc\fR زیرعنوان \fIOverrides\fR را در مستنداتِ متدِ بازنویسی‌کننده تولید می‌کند\&. پیوندی به متدی که بازنویسی شده اضافه می‌شود، چه کامنت به ارث برده شده باشد چه نشده باشد\&. .PP در حالت سوم، هنگامی که یک متد در یک کلاس مشخص، متدی را در یک رابط پیاده‌سازی می‌کند، دستور \f3javadoc\fR زیرعنوان \fISpecified by\fR را در مستنداتِ متدِ پیاده‌سازی‌کننده تولید می‌کند\&. پیوندی به متدی که پیاده‌سازی شده قرار می‌گیرد، چه کامنت به ارث برده شده باشد چه نشده باشد\&. .SS "الگوریتم کامنت‌های متد (METHOD COMMENTS ALGORITHM)" اگر متدی کامنت مستندسازی نداشته باشد، یا شامل برچسب \f3{@inheritDoc}\fR باشد، دستور \f3javadoc\fR از الگوریتم زیر برای یافتن یک کامنت کاربردی استفاده می‌کند\&. این الگوریتم طوری طراحی شده است که خاص‌ترین کامنت مستندسازیِ قابل‌اعمال را بیابد و رابط‌ها را بر سوپرکلاس‌ها ترجیح دهد: .TP 0.4i 1\&. در هر رابطِ مستقیماً پیاده‌سازی‌شده (یا ارث‌بری‌شده/extended) به ترتیبی که پس از کلمه \f3implements\fR (یا \f3extends\fR) در اعلان متد ظاهر می‌شوند، جستجو کنید\&. از اولین کامنت مستندسازی یافت‌شده برای این متد استفاده کنید\&. .TP 0.4i 2\&. اگر مرحله ۱ در یافتن کامنت مستندسازی ناموفق بود، کل این الگوریتم را به صورت بازگشتی بر روی هر رابط مستقیماً پیاده‌سازی‌شده (یا ارث‌بری‌شده) به همان ترتیبی که در مرحله ۱ بررسی شدند، اعمال کنید\&. .TP 0.4i 3\&. هنگامی که مرحله ۲ در یافتن کامنت مستندسازی ناموفق باشد و این ساختار، کلاسی به غیر از کلاس \f3Object\fR باشد (نه یک رابط): .RS .TP 0.4i 1\&. اگر سوپرکلاس دارای یک کامنت مستندسازی برای این متد است، از آن استفاده کنید\&. .TP 0.4i 2\&. اگر مرحله ۳-الف در یافتن کامنت مستندسازی ناموفق بود، کل این الگوریتم را به صورت بازگشتی روی سوپرکلاس اعمال کنید\&. .RE .SH "برچسب‌های جاوا داک (JAVADOC TAGS)" دستور \f3javadoc\fR برچسب‌های ویژه‌ای را که درون کامنت مستندسازی جاوا قرار گرفته‌اند تجزیه می‌کند\&. برچسب‌های \f3javadoc\fR به شما امکان می‌دهند تا یک API کامل و خوش‌قالب را به طور خودکار از کد منبع خود تولید کنید\&. این برچسب‌ها با علامت اتساین (\f3@\fR) آغاز می‌شوند و حساس به بزرگ و کوچکی حروف هستند\&. آن‌ها باید با حروف بزرگ و کوچک دقیقاً همان‌گونه که نشان داده شده‌اند تایپ شوند\&. یک برچسب باید در ابتدای خط (پس از هر فاصله ابتدایی و ستاره اختیاری) آغاز شود، در غیر این صورت به عنوان متن در نظر گرفته می‌شود\&. طبق عرف، برچسب‌های هم‌نام با هم گروه‌بندی می‌شوند؛ برای مثال، تمام برچسب‌های \f3@see\fR را کنار هم قرار دهید\&. برای اطلاعات بیشتر، بخش «مکان‌های قابل استفاده برای برچسب‌ها» (Where Tags Can Be Used) را ببینید\&. .PP برچسب‌ها دارای انواع زیر هستند: .TP 0.2i \(bu برچسب‌های بلوکی (Block tags): برچسب‌های بلوکی را تنها در بخش برچسب‌ها که پس از توضیحات می‌آید قرار دهید\&. برچسب‌های بلوکی به شکل \fI@tag\fR هستند\&. .TP 0.2i \(bu برچسب‌های درون‌خطی (Inline tags): برچسب‌های درون‌خطی را در هر کجای توضیحات اصلی یا در کامنت‌های برچسب‌های بلوکی قرار دهید\&. برچسب‌های درون‌خطی در میان آکولادها محصور می‌شوند: \fI{@tag}\fR\&. .PP برای برچسب‌های سفارشی، گزینه \f3-tag tagname:Xaoptcmf:"taghead"\fR را ببینید\&. همچنین بخش «مکان‌های قابل استفاده برای برچسب‌ها» (Where Tags Can Be Used) را ببینید\&. .SS "شرح برچسب‌ها (TAG DESCRIPTIONS)" .TP @author \fIname-text\fR معرفی‌شده در JDK 1\&.0 هنگامی که از گزینه \f3-author\fR استفاده می‌شود، یک مدخل «Author» با متن نام مشخص‌شده به اسناد تولیدشده اضافه می‌کند\&. یک کامنت مستندسازی می‌تواند شامل چندین برچسب \f3@author\fR باشد\&. شما می‌توانید در هر برچسب \f3@author\fR یک نام، یا در هر برچسب چندین نام را مشخص کنید\&. در حالت اول، دستور \f3javadoc\fR یک ویرگول (,) و یک فاصله بین نام‌ها درج می‌کند\&. در حالت دوم، تمام متن بدون تجزیه شدن در سند تولیدشده کپی می‌شود\&. بنابراین، اگر جداکننده نامِ بومی‌سازی‌شده دیگری به غیر از ویرگول می‌خواهید، می‌توانید از چندین نام در یک خط استفاده کنید\&. مدخل @author را در How to Write Doc Comments for the Javadoc Tool در http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137868\&.html#@author ببینید\&. .TP {@code \fItext\fR} معرفی‌شده در JDK 1\&.5 معادل با \f3<code>{@literal}</code>\fR\&. متن را با قلم کد (code font) بدون تفسیر آن به عنوان نشانه‌گذاری HTML یا برچسب‌های تودرتوی Javadoc نمایش می‌دهد\&. این امکان را به شما می‌دهد تا به جای موجودیت‌های HTML (\f3<\fR و \f3>\fR)، از براکت‌های شکسته معمولی (< و >) در کامنت‌های مستندسازی استفاده کنید، مانند انواع پارامترها (\f3<Object>\fR)، نابرابری‌ها (\f33 < 4\fR) یا فلش‌ها (\f3<-\fR)\&. برای مثال، متن کامنت مستندسازی \f3{@code A<B>C}\fR در صفحه HTML تولیدشده بدون تغییر به صورت \f3A<B>C\fR نمایش داده می‌شود\&. این بدان معنی است که \f3<B>\fR به عنوان پررنگ (bold) تفسیر نمی‌شود و با قلم کد است\&. اگر همین عملکرد را بدون قلم کد می‌خواهید، از برچسب \f3{@literal}\fR استفاده کنید\&. .TP @deprecated \fIdeprecated-text\fR معرفی‌شده در JDK 1\&.0 یادداشتی اضافه می‌کند که نشان می‌دهد این API دیگر نباید استفاده شود (حتی اگر هنوز کار کند)\&. دستور \f3javadoc\fR متن \f3deprecated-text\fR را به قبل از توضیحات اصلی منتقل کرده، آن را با قلم مورب قرار می‌دهد و پیش از آن هشداری برجسته اضافه می‌کند: Deprecated\&. این برچسب در تمام کامنت‌های مستندسازی معتبر است: overview، package، class، interface، constructor، method و field\&. جمله اولِ متن منسوخ‌شده باید به کاربر بگوید که این API چه زمانی منسوخ شده و از چه چیزی به عنوان جایگزین استفاده کند\&. دستور \f3javadoc\fR جمله اول را در بخش خلاصه و نمایه (index) کپی می‌کند\&. جملات بعدی می‌توانند دلیل منسوخ شدن آن را نیز توضیح دهند\&. شما باید یک برچسب \f3{@link}\fR (برای Javadoc 1\&.2 یا بالاتر) اضافه کنید که به API جایگزین اشاره داشته باشد\&. برای منسوخ کردن یک عنصر برنامه، از برچسب حاشیه‌نویسی \fI@deprecated annotation\fR استفاده کنید\&. بخش 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 ببینید\&. .TP {@docRoot} معرفی‌شده در JDK 1\&.3 مسیر نسبی به دایرکتوری ریشه (مقصد) سند تولیدشده را از هر صفحه تولیدشده نشان می‌دهد\&. این برچسب زمانی مفید است که بخواهید فایلی، مانند یک صفحه کپی‌رایت یا نشان‌واره شرکت را بگنجانید که می‌خواهید از تمام صفحات تولیدشده به آن ارجاع داده شود\&. پیوند دادن به صفحه کپی‌رایت از پایین هر صفحه متداول است\&. این برچسب \f3{@docRoot}\fR می‌تواند هم در خط فرمان و هم در کامنت مستندسازی استفاده شود\&. این برچسب در تمام کامنت‌های مستندسازی معتبر است: overview، package، class، interface، constructor، method و field، و شامل بخش متنی هر برچسبی (مانند برچسب‌های \f3@return\fR، \f3@param\fR و \f3@deprecated\fR) می‌شود\&. .RS .TP 0.2i \(bu در خط فرمان، جایی که سربرگ، پاورقی یا پایین صفحه تعریف شده‌اند: \f3javadoc -bottom \&'<a href="{@docRoot}/copyright\&.html">Copyright</a>\&'\fR\&. هنگامی که از برچسب \f3{@docRoot}\fR بدین صورت در یک makefile استفاده می‌کنید، برخی از برنامه‌های \f3makefile\fR نیاز به روش خاصی برای گریز دادن (escape کردن) کاراکترهای آکولاد \f3{}\fR دارند\&. برای مثال، نسخه 5\&.2 از Inprise MAKE که در Windows اجرا می‌شود به آکولاد دوتایی نیاز دارد: \f3{{@docRoot}}\fR\&. همچنین لازم دارد تا آرگومان‌های گزینه‌هایی مانند گزینه \f3-bottom\fR در علامت‌های نقل‌قول دوتایی (به جای تکی) محصور شوند (همراه با حذف علامت‌های نقل‌قول در اطراف آرگومان \f3href\fR)\&. .TP 0.2i \(bu در کامنت مستندسازی: .sp .nf \f3/**\fP .fi .nf \f3 * See the <a href="{@docRoot}/copyright\&.html">Copyright</a>\&.\fP .fi .nf \f3 */\fP .fi .nf \f3\fP .fi .sp این برچسب لازم است زیرا اسناد تولیدشده در دایرکتوری‌های سلسله‌مراتبی قرار می‌گیرند، با عمقی به اندازه تعداد زیربسته‌ها (subpackages)\&. عبارت: \f3<a href="{@docRoot}/copyright\&.html">\fR برای \f3java/lang/Object\&.java\fR به \f3<a href="\&.\&./\&.\&./copyright\&.html">\fR و برای \f3java/lang/ref/Reference\&.java\fR به \f3<a href="\&.\&./\&.\&./\&.\&./copyright\&.html">\fR تبدیل می‌شود\&. .RE .TP @exception \fIclass-name description\fR معرفی‌شده در JDK 1\&.0 کاملاً مشابه برچسب \f3@throws\fR است\&. مدخل @throws class-name description را ببینید\&. .TP {@inheritDoc} معرفی‌شده در JDK 1\&.4 مستندات را از نزدیک‌ترین کلاس با قابلیت ارث‌بری یا رابط قابل‌پیاده‌سازی در محل این برچسب به داخل کامنت مستندسازی فعلی به ارث می‌برد (کپی می‌کند)\&. این امکان به شما اجازه می‌دهد تا در سطوح بالاتر درخت وراثت کامنت‌های عمومی‌تری بنویسید و در اطراف متن کپی‌شده توضیحات اختصاصی اضافه کنید\&. این برچسب تنها در این مکان‌ها درون یک کامنت مستندسازی معتبر است: .RS .TP 0.2i \(bu در بلوک توضیحات اصلی یک متد\&. در این حالت، توضیحات اصلی از یک کلاس یا رابط در سطوح بالاتر سلسله‌مراتب کپی می‌شود\&. .TP 0.2i \(bu در آرگومان‌های متنی برچسب‌های \f3@return\fR، \f3@param\fR و \f3@throws\fR متعلق به یک متد\&. در این حالت، متن برچسب از برچسب متناظر در سطوح بالاتر سلسله‌مراتب کپی می‌شود\&. .RE برای شرح نحوه یافتن کامنت‌ها در سلسله‌مراتب وراثت، بخش «وراثت کامنت متد» (Method Comment Inheritance) را ببینید\&. توجه داشته باشید که اگر این برچسب غایب باشد، کامنت طبق قوانینی که در آن بخش توضیح داده شده است، به طور خودکار به ارث می‌رسد یا به ارث نمی‌رسد\&. .TP {@link \fIpackage\&.class#member label\fR} معرفی‌شده در JDK 1\&.2 یک پیوند درون‌خطی با یک برچسب متنیِ قابل‌مشاهده درج می‌کند که به مستندات بسته، کلاس، یا نام عضو مشخص‌شده از یک کلاس مرجع اشاره دارد\&. این برچسب در تمام کامنت‌های مستندسازی معتبر است: overview، package، class، interface، constructor، method و field، شامل بخش متنی هر برچسبی مانند برچسب‌های \f3@return\fR، \f3@param\fR و \f3@deprecated\fR\&. مدخل @link را در How to Write Doc Comments for the Javadoc Tool در http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137868\&.html#{@link ببینید\&. این برچسب مشابه برچسب \f3@see\fR است\&. هر دو برچسب به مراجع یکسانی نیاز دارند و ساختار نگارشی (syntax) یکسانی را برای \f3package\&.class#member\fR و \f3label\fR می‌پذیرند\&. تفاوت اصلی در این است که برچسب \f3{@link}\fR به جای قرار دادن پیوند در بخش «همچنین ببینید»، یک پیوند درون‌خطی تولید می‌کند\&. برچسب \f3{@link}\fR با آکولاد باز و بسته می‌شود تا از بقیه متن درون‌خطی جدا گردد\&. اگر نیاز دارید در داخل برچسب متنی (label) از آکولاد راست (\f3}\fR) استفاده کنید، از نمایش موجودیت HTML یعنی \f3}\fR استفاده نمایید\&. هیچ محدودیتی در تعداد برچسب‌های \f3{@link}\fR مجاز در یک جمله وجود ندارد\&. شما می‌توانید از این برچسب در بخش توضیحات اصلی هر کامنت مستندسازی یا در بخش متنی هر برچسبی مانند برچسب‌های \f3@deprecated\fR، \f3@return\fR یا \f3@param\fR استفاده کنید\&. برای مثال، در اینجا کامنتی آورده شده است که به متد \f3getComponentAt(int, int)\fR ارجاع می‌دهد: .sp .nf \f3Use the {@link #getComponentAt(int, int) getComponentAt} method\&.\fP .fi .nf \f3\fP .fi .sp از این کد، doclet استاندارد کد HTML زیر را تولید می‌کند (با این فرض که به کلاس دیگری در همان بسته ارجاع می‌دهد): .sp .nf \f3Use the <a href="Component\&.html#getComponentAt(int, int)">getComponentAt</a> method\&.\fP .fi .nf \f3\fP .fi .sp خط قبلی در صفحه وب به این صورت ظاهر می‌شود: .sp .nf \f3Use the getComponentAt method\&.\fP .fi .nf \f3\fP .fi .sp .TP {@linkplain \fIpackage\&.class#member label\fR} معرفی‌شده در JDK 1\&.4 همانند برچسب \f3{@link}\fR عمل می‌کند، جز اینکه متن پیوند به جای قلم کد با متن ساده نمایش داده می‌شود\&. زمانی که برچسب متنی یک متن عادی است، مفید است\&. برای مثال، \f3Refer to {@linkplain add() the overridden method}\fR به صورت زیر نمایش می‌یابد: Refer to the overridden method\&. .TP {@literal \fItext\fR} معرفی‌شده در JDK 1\&.5 متن را بدون تفسیر آن به عنوان نشانه‌گذاری HTML یا برچسب‌های تودرتوی Javadoc نمایش می‌دهد\&. این امکان به شما اجازه می‌دهد تا در کامنت‌های مستندسازی به جای موجودیت‌های HTML (\f3<\fR و \f3>\fR)، از براکت‌های شکسته (\f3< و >\fR) استفاده کنید، مانند انواع پارامترها (\f3<Object>\fR)، نابرابری‌ها (\f33 < 4\fR) یا فلش‌ها (<-)\&. برای مثال، متن کامنت مستندسازی \f3{@literal A<B>C}\fR در صفحه HTML تولیدشده در مرورگر شما بدون تغییر به صورت \f3A<B>C\fR نمایش می‌یابد\&. عبارت \f3<B>\fR به عنوان پررنگ (bold) تفسیر نمی‌شود (و با قلم کد نیز نمایش داده نمی‌شود)\&. اگر می‌خواهید همین عملکرد را با متن در قلم کد داشته باشید، از برچسب \f3{@code}\fR استفاده کنید\&..TP @param \fIparameter-name description\fR معرفی‌شده در JDK 1\&.0 پارامتری با \f3parameter-name\fR مشخص‌شده به همراه توضیحات تعیین‌شده به بخش Parameters اضافه می‌کند\&. هنگام نوشتن کامنت مستندسازی، می‌توانید توضیحات را در چندین خط ادامه دهید\&. این برچسب تنها در کامنت مستندسازی یک متد، سازنده یا کلاس معتبر است\&. بخش @param را در How to Write Doc Comments for the Javadoc Tool در آدرس http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137868\&.html#@param ببینید\&. مقدار \f3parameter-name\fR می‌تواند نام یک پارامتر در متد یا سازنده، یا نام یک پارامتر نوع (type parameter) برای یک کلاس، متد، یا سازنده باشد\&. برای مشخص کردن استفاده از یک پارامتر نوع، از علامت‌های کوچکتری/بزرگتری (< >) در اطراف نام این پارامتر استفاده کنید\&. مثالی از پارامتر نوع برای یک کلاس: .sp .nf \f3/**\fP .fi .nf \f3 * @param <E> Type of element stored in a list\fP .fi .nf \f3 */\fP .fi .nf \f3public interface List<E> extends Collection<E> {\fP .fi .nf \f3}\fP .fi .nf \f3\fP .fi .sp مثالی از پارامتر نوع برای یک متد: .sp .nf \f3/**\fP .fi .nf \f3 * @param string the string to be converted\fP .fi .nf \f3 * @param type the type to convert the string to\fP .fi .nf \f3 * @param <T> the type of the element\fP .fi .nf \f3 * @param <V> the value of the element\fP .fi .nf \f3 */\fP .fi .nf \f3<T, V extends T> V convert(String string, Class<T> type) {\fP .fi .nf \f3}\fP .fi .nf \f3\fP .fi .sp .TP @return \fIdescription\fR معرفی‌شده در 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 ببینید\&. .TP @see \fIreference\fR معرفی‌شده در JDK 1\&.0 یک عنوان \fISee Also\fR به همراه پیوند یا مدخل متنی که به یک مرجع اشاره دارد، اضافه می‌کند\&. یک کامنت مستندسازی می‌تواند شامل هر تعداد برچسب \f3@see\fR باشد که همگی ذیل یک عنوان گروه‌بندی می‌شوند\&. برچسب \f3@see\fR دارای سه حالت مختلف است\&. این فرم رایج‌ترین حالت است\&. این برچسب در هر کامنت مستندسازی معتبر است: مرور کلی (overview)، بسته، کلاس، رابط، سازنده، متد یا فیلد\&. برای قرار دادن یک پیوند درون‌خطی در یک جمله به یک بسته، کلاس یا عضو، \f3{@link}\fR را ببینید\&. \fIفرم ۱\fR\&. فرم برچسب @see \f3string\fR یک مدخل متنی برای \fIstring\fR اضافه می‌کند\&. هیچ پیوندی تولید نمی‌شود\&. این رشته نشان‌دهنده یک کتاب یا مرجع دیگری برای اطلاعاتی است که از طریق URL در دسترس نیست\&. دستور \f3javadoc\fR این حالت را با جستجوی یک علامت نقل‌قول جفتی (") به عنوان نویسه اول، از موارد پیشین تشخیص می‌دهد\&. برای مثال، \f3@see "The Java Programming Language"\fR که متن زیر را تولید می‌کند: \fISee Also\fR: "The Java Programming Language" \fIفرم ۲\fR\&. فرم \f3@see <a href="URL#value">label</a>\fR پیوندی را به صورت تعریف‌شده توسط \f3URL#value\fR اضافه می‌کند\&. پارامتر \f3URL#value\fR یک URL نسبی یا مطلق است\&. دستور \f3javadoc\fR این حالت را با جستجوی نماد کوچکتری (\f3<\fR) به عنوان نویسه اول، از سایر موارد تشخیص می‌دهد\&. برای مثال، \f3@see <a href="spec\&.html#section">Java Spec</a>\fR پیوند زیر را تولید می‌کند: \fISee Also\fR: Java Spec \fIفرم ۳\fR\&. فرم \f3@see package\&.class#member label\fR پیوندی را به همراه یک برچسب متنی قابل‌مشاهده اضافه می‌کند که به مستندات نام مشخص‌شده و ارجاع‌یافته در زبان Java اشاره دارد\&. برچسب (label) اختیاری است\&. در صورت حذف برچسب، نام به جای آن به صورت متنی قابل‌مشاهده و به طور مناسب کوتاه‌شده نمایش داده می‌شود\&. از گزینه \f3-noqualifier\fR برای حذف سراسری نام بسته از این متن قابل‌مشاهده استفاده کنید\&. زمانی از برچسب استفاده کنید که می‌خواهید متن قابل‌مشاهده با متنِ تولیدشده به صورت خودکار متفاوت باشد\&. بخش How a Name Appears را ببینید\&. تنها در Java SE 1\&.2، نام (و نه برچسب) به طور خودکار درون برچسب‌های HTML \f3<code>\fR قرار می‌گیرد\&. با شروع از Java SE 1\&.2\&.2، برچسب \f3<code>\fR همیشه در اطراف متن قابل‌مشاهده قرار می‌گیرد، خواه از برچسب استفاده شده باشد یا نه\&. .RS .TP 0.2i \(bu عبارت \f3package\&.class#member\fR هر نام معتبری از عناصر برنامه است که به آن ارجاع داده شده، مانند نام بسته، کلاس، رابط، سازنده، متد یا فیلد، با این تفاوت که نویسه قبل از نام عضو باید علامت نامبر ساین (\f3#\fR) باشد\&. کلاس نشان‌دهنده هر کلاس یا رابط سطح‌بالا (top-level) یا تو در تو است\&. عضو نشان‌دهنده هر سازنده، متد یا فیلد است (نه یک کلاس یا رابط تو در تو)\&. اگر این نام در کلاس‌های مستندسازی‌شده باشد، دستور \f3javadoc\fR پیوندی به آن ایجاد می‌کند\&. برای ایجاد پیوند به کلاس‌های ارجاع‌یافته خارجی، از گزینه \f3-link\fR استفاده کنید\&. برای ارجاع به مستندات نامی که متعلق به یک کلاس ارجاع‌شده نیست، از هر یک از دو فرم دیگر برچسب \f3@see\fR استفاده کنید\&. بخش Specify a Name را ببینید\&. \fIنکته:\fR کلاس‌های ارجاع‌یافته خارجی کلاس‌هایی هستند که در خط فرمان به دستور \f3javadoc\fR ارسال نشده‌اند\&. پیوندهای موجود در مستندات تولیدشده به کلاس‌های ارجاع‌یافته خارجی، مراجع خارجی (external references) یا پیوندهای خارجی نامیده می‌شوند\&. برای نمونه، اگر دستور \f3javadoc\fR را فقط روی بسته \f3java\&.awt\fR اجرا کنید، هر کلاسی در \f3java\&.lang\fR، مانند \f3Object\fR، یک کلاس ارجاع‌یافته خارجی خواهد بود\&. از گزینه‌های \f3-link\fR و \f3-linkoffline\fR برای ایجاد پیوند به کلاس‌های ارجاع‌یافته خارجی استفاده کنید\&. کامنت‌های سورس‌کد کلاس‌های ارجاع‌یافته خارجی در هنگام اجرای دستور \f3javadoc\fR در دسترس نیستند\&. .TP 0.2i \(bu مقدار \f3label\fR متن اختیاری است که به عنوان عنوان پیوند قابل‌مشاهده است\&. برچسب می‌تواند حاوی نویسه‌های فاصله سفید (white space) باشد\&. در صورت حذف \f3label\fR، عبارت \f3package\&.class\&.member\fR به صورت متناسب کوتاه‌شده نسبت به کلاس و بسته جاری نمایش داده می‌شود\&. بخش How a Name Appears را ببینید\&. .TP 0.2i \(bu یک فاصله (space) جداکننده بین \f3package\&.class#member\fR و \f3label\fR است\&. فاصله داخل پرانتز نشان‌دهنده شروع برچسب نیست، بنابراین می‌توان از فاصله‌ها بین پارامترها در یک متد استفاده کرد\&. .RE \fI\fRدر مثال زیر، یک برچسب \f3@see\fR (در کلاس \f3Character\fR) به متد equals در کلاس \f3String\fR ارجاع می‌دهد\&. این برچسب شامل هر دو آرگومان است: نام \f3String#equals(Object)\fR و برچسب \f3equals\fR\&. .sp .nf \f3/**\fP .fi .nf \f3 * @see String#equals(Object) equals\fP .fi .nf \f3 */\fP .fi .nf \f3\fP .fi .sp داکلت استاندارد HTML مشابه زیر را تولید می‌کند: .sp .nf \f3<dl>\fP .fi .nf \f3<dt><b>See Also:</b>\fP .fi .nf \f3<dd><a href="\&.\&./\&.\&./java/lang/String#equals(java\&.lang\&.Object)"><code>equals<code></a>\fP .fi .nf \f3</dl>\fP .fi .nf \f3\fP .fi .sp کد پیشین در یک مرورگر مشابه زیر خواهد بود، جایی که برچسب متن پیوند قابل‌مشاهده است: \fISee Also\fR: equals .PP مشخص کردن نام (Specify a Name) \fI\fRاین نام \f3package\&.class#member\fR می‌تواند کاملاً مقید باشد، مانند \f3java\&.lang\&.String#toUpperCase()\fR یا غیرمقید باشد، مانند \f3String#toUpperCase()\fR یا \f3#toUpperCase()\fR\&. اگر نام کمتر از حالت کامل مقید باشد، دستور \f3javadoc\fR از ترتیب جستجوی استاندارد کامپایلر Java برای یافتن آن استفاده می‌کند\&. بخش Search Order for the @see Tag را ببینید\&. نام می‌تواند حاوی فاصله سفید در داخل پرانتزها باشد، مانند بین آرگومان‌های متد\&. مزیت ارائه نام‌های کوتاه‌تر و تا حدی مقید این است که تایپ آنها کوتاه‌تر بوده و آشفتگی کمتری در کد منبع وجود دارد\&. فهرست زیر فرم‌های مختلف نام را نشان می‌دهد که در آن \f3Class\fR می‌تواند یک کلاس یا رابط باشد؛ Type می‌تواند یک کلاس، رابط، آرایه یا نوع اولیه (primitive) باشد؛ و method می‌تواند یک متد یا سازنده باشد\&. .sp .nf \f3\fIفرم‌های رایج برای\fR\fI @see package\&.class#member\fR\fP .fi .nf \f3\fIارجاع به عضوی از کلاس جاری\fR\fP .fi .nf \f3@see #field\fP .fi .nf \f3@see #method(Type, Type,\&.\&.\&.)\fP .fi .nf \f3@see #method(Type argname, Type argname,\&.\&.\&.)\fP .fi .nf \f3@see #constructor(Type, Type,\&.\&.\&.)\fP .fi .nf \f3@see #constructor(Type argname, Type argname,\&.\&.\&.) \fP .fi .nf \f3\fP .fi .nf \f3\fIارجاع به کلاسی دیگر در بسته‌های جاری یا واردشده\fR\fP .fi .nf \f3@see Class#field\fP .fi .nf \f3@see Class#method(Type, Type,\&.\&.\&.)\fP .fi .nf \f3@see Class#method(Type argname, Type argname,\&.\&.\&.)\fP .fi .nf \f3@see Class#constructor(Type, Type,\&.\&.\&.)\fP .fi .nf \f3@see Class#constructor(Type argname, Type argname,\&.\&.\&.)\fP .fi .nf \f3@see Class\&.NestedClass\fP .fi .nf \f3@see Class \fP .fi .nf \f3\fP .fi .nf \f3\fIارجاع به عنصری در بسته‌ای دیگر (کاملاً مقید)\fR\fP .fi .nf \f3@see package\&.Class#field\fP .fi .nf \f3@see package\&.Class#method(Type, Type,\&.\&.\&.)\fP .fi .nf \f3@see package\&.Class#method(Type argname, Type argname,\&.\&.\&.)\fP .fi .nf \f3@see package\&.Class#constructor(Type, Type,\&.\&.\&.)\fP .fi .nf \f3@see package\&.Class#constructor(Type argname, Type argname,\&.\&.\&.)\fP .fi .nf \f3@see package\&.Class\&.NestedClass\fP .fi .nf \f3@see package\&.Class\fP .fi .nf \f3@see package\fP .fi .nf \f3\fP .fi .sp \f3\fRنکاتی درباره فهرست پیشین:.TP 0.2i \(bu مجموعه اول از ساختارها بدون کلاس یا بسته، باعث می‌شود دستور \f3javadoc\fR تنها در سلسله‌مراتب کلاس فعلی جستجو کند\&. این دستور عضوی از کلاس یا رابط فعلی، یکی از ابرکلاس‌ها یا ابررابط‌های آن، یا یکی از کلاس‌ها یا رابط‌های دربرگیرنده آن را پیدا می‌کند (موارد جستجوی ۱\(en۳)\&. این حالت سایر بخش‌های بسته فعلی یا بسته‌های دیگر را جستجو نمی‌کند (موارد جستجوی ۴\(en۵)\&. بخش «ترتیب جستجو برای برچسب @see» را ببینید\&. .TP 0.2i \(bu اگر هر متد یا سازنده‌ای به‌صورت یک نام بدون پرانتز وارد شود، مانند \f3getValue\fR، و فیلدی با همان نام وجود نداشته باشد، دستور \f3javadoc\fR همچنان پیوندی به آن متد ایجاد می‌کند\&. اگر این متد سربارگذاری شده باشد (overloaded)، دستور \f3javadoc\fR به نخستین متدی که در جستجوی خود با آن مواجه شود پیوند می‌دهد، که نامعین است\&. .TP 0.2i \(bu کلاس‌های تودرتو (nested classes) باید برای همه فرم‌ها به‌صورت \f3outer\&.inner\fR مشخص شوند، نه صرفاً به‌صورت \f3inner\fR\&. .TP 0.2i \(bu همان‌طور که بیان شد، علامت هش (\f3#\fR) به جای نقطه (\f3\&.\fR) یک عضو را از کلاسش جدا می‌کند\&. این امر دستور \f3javadoc\fR را قادر می‌سازد تا ابهامات را برطرف کند، چرا که نقطه برای جداسازی کلاس‌ها، کلاس‌های تودرتو، بسته‌ها و زیربسته‌ها نیز به کار می‌رود\&. با این حال، دستور \f3javadoc\fR در صورت نبود ابهام، نقطه را به درستی تجزیه می‌کند، اما یک هشدار جهت آگاهی شما چاپ می‌کند\&. .PP ترتیب جستجو برای برچسب @see \fI\fRدستور \f3javadoc\fR برچسب \f3@see\fR را که در یک فایل مبدأ، فایل بسته یا فایل مروری ظاهر می‌شود، پردازش می‌کند\&. در دو فایل آخر، باید نامی را که همراه با برچسب \f3@see\fR ارائه می‌دهید، به‌طور کامل واجد شرایط (fully qualified) کنید\&. در یک فایل مبدأ، می‌توانید نامی را مشخص کنید که به‌صورت کامل یا جزئی واجد شرایط (fully qualified یا partially qualified) باشد\&. .PP در ادامه، ترتیب جستجو برای برچسب \f3@see\fR آمده است\&. .TP 0.4i 1\&. کلاس یا رابط فعلی\&. .TP 0.4i 2\&. هر یک از کلاس‌ها و رابط‌های دربرگیرنده، با جستجوی نزدیک‌ترین آن‌ها در ابتدا\&. .TP 0.4i 3\&. هر یک از ابرکلاس‌ها و ابررابط‌ها، با جستجوی نزدیک‌ترین آن‌ها در ابتدا\&. .TP 0.4i 4\&. بسته فعلی\&. .TP 0.4i 5\&. هر یک از بسته‌ها، کلاس‌ها و رابط‌های واردشده (imported)، با جستجو به ترتیبی که در عبارت‌های \f3import\fR آمده‌اند\&. .PP دستور \f3javadoc\fR برای هر کلاسی که با آن مواجه می‌شود، جستجو را به‌صورت بازگشتی در موارد ۱ تا ۳ ادامه می‌دهد تا زمانی که یک تطابق پیدا کند\&. بدین معنا که پس از جستجو در کلاس فعلی و کلاس دربرگیرنده آن E، پیش از کلاس‌های دربرگیرنده E، در ابرکلاس‌های E جستجو می‌کند\&. در موارد ۴ و ۵، دستور \f3javadoc\fR کلاس‌ها یا رابط‌های درون یک بسته را با ترتیب مشخصی جستجو نمی‌کند (این ترتیب به کامپایلر بستگی دارد)\&. در مورد ۵، دستور \f3javadoc\fR در \fIjava\&.lang\fR جستجو می‌کند زیرا توسط تمام برنامه‌ها وارد شده است\&. .PP هنگامی که دستور \f3javadoc\fR در یک فایل مبدأ با برچسب \f3@see\fR مواجه می‌شود که نام آن به‌طور کامل واجد شرایط نشده است، نام مشخص‌شده را با همان ترتیبی جستجو می‌کند که کامپایلر جاوا جستجو می‌کند؛ با این تفاوت که دستور \f3javadoc\fR برخی از ابهامات فضای نام را تشخیص نمی‌دهد زیرا فرض می‌کند کد مبدأ عاری از این خطاهاست\&. این ترتیب جستجو به‌طور رسمی در «مشخصات زبان جاوا» (Java Language Specification) تعریف شده است\&. دستور \f3javadoc\fR آن نام را در تمامی کلاس‌ها و بسته‌های مرتبط و واردشده جستجو می‌کند\&. به‌ویژه، با این ترتیب جستجو می‌کند: .TP 0.4i 1\&. کلاس یا رابط فعلی\&. .TP 0.4i 2\&. هر یک از کلاس‌ها و رابط‌های دربرگیرنده، با جستجوی نزدیک‌ترین آن‌ها در ابتدا\&. .TP 0.4i 3\&. هر یک از ابرکلاس‌ها و ابررابط‌ها، با جستجوی نزدیک‌ترین آن‌ها در ابتدا\&. .TP 0.4i 4\&. بسته فعلی\&. .TP 0.4i 5\&. هر یک از بسته‌ها، کلاس‌ها و رابط‌های واردشده، با جستجو به ترتیبی که در عبارت‌های \f3import\fR آمده‌اند\&. .PP دستور \f3javadoc\fR لزوماً در زیرکلاس‌ها جستجو نمی‌کند، و در بسته‌های دیگر نیز جستجو نخواهد کرد، حتی اگر مستندات آن‌ها در همان نوبت اجرا تولید شود\&. برای مثال، اگر برچسب \f3@see\fR در کلاس \f3java\&.awt\&.event\&.KeyEvent\fR باشد و به نامی در بسته \f3java\&.awt package\fR اشاره کند، دستور \f3javadoc\fR در آن بسته جستجو نخواهد کرد مگر اینکه آن کلاس آن را وارد (import) کرده باشد\&. .PP نحوه نمایش نام \fI\fRاگر \f3label\fR حذف شود، عبارت \f3package\&.class\&.member\fR نمایش داده می‌شود\&. به‌طور کلی، نسبت به کلاس و بسته فعلی به‌طور مناسبی کوتاه می‌شود\&. کوتاه شدن به این معناست که دستور \f3javadoc\fR تنها حداقل نام مورد نیاز را نمایش می‌دهد\&. برای مثال، اگر متد \f3String\&.toUpperCase()\fR شامل ارجاعاتی به عضوی از همان کلاس و عضوی از یک کلاس دیگر باشد، نام کلاس تنها در مورد دوم نمایش داده می‌شود، همان‌طور که در فهرست زیر نشان داده شده است\&. از گزینه \f3-noqualifier\fR برای حذف سراسری نام بسته‌ها استفاده کنید\&. .PP \fIنوع ارجاع\fR: برچسب \f3@see\fR به عضوی از همان کلاس در همان بسته اشاره دارد .br \fIمثال در\fR: \f3@see String#toLowerCase()\fR .br \fIنمایش به‌صورت\fR: \f3toLowerCase()\fR \- نام‌های بسته و کلاس حذف می‌شوند .br .PP \fIنوع ارجاع\fR: برچسب \f3@see\fR به عضوی از کلاسی دیگر در همان بسته اشاره دارد .br \fIمثال در\fR: \f3@see Character#toLowerCase(char)\fR .br \fIنمایش به‌صورت\fR: \f3Character\&.toLowerCase(char)\fR \- نام بسته حذف می‌شود، نام کلاس درج می‌شود .br .PP \fIنوع ارجاع\fR: برچسب \f3@see\fR به عضوی از کلاسی دیگر در بسته‌ای دیگر اشاره دارد .br \fIمثال در\fR: \f3@see java\&.io\&.File#exists()\fR .br \fIنمایش به‌صورت\fR: \f3java\&.io\&.File\&.exists()\fR \- نام‌های بسته و کلاس درج می‌شوند .br .PP مثال‌هایی از برچسب @see توضیحات سمت راست نشان می‌دهند که نام چگونه ظاهر می‌شود هنگامی که برچسب \f3@see\fR در کلاسی در بسته‌ای دیگر قرار دارد، مانند \f3java\&.applet\&.Applet\fR\&. بخش @see را در «نحوه نگارش توضیحات مستندسازی برای ابزار Javadoc» در http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137868\&.html#@see ببینید\&. .sp .nf \f3 See also:\fP .fi .nf \f3@see java\&.lang\&.String // String \fP .fi .nf \f3@see java\&.lang\&.String The String class // The String class \fP .fi .nf \f3@see String // String \fP .fi .nf \f3@see String#equals(Object) // String\&.equals(Object) \fP .fi .nf \f3@see String#equals // String\&.equals(java\&.lang\&.Object) \fP .fi .nf \f3@see java\&.lang\&.Object#wait(long) // java\&.lang\&.Object\&.wait(long) \fP .fi .nf \f3@see Character#MAX_RADIX // Character\&.MAX_RADIX \fP .fi .nf \f3@see <a href="spec\&.html">Java Spec</a> // Java Spec \fP .fi .nf \f3@see "The Java Programming Language" // "The Java Programming Language" \fP .fi .nf \f3\fP .fi .sp \fIنکته:\fR می‌توانید برچسب \f3@se\fR\f3e\fR را گسترش دهید تا با استفاده از گزینه \f3-link\fR به کلاس‌هایی که مستندسازی نمی‌شوند پیوند برقرار کنید\&. .TP @serial \fIfield-description\fR | 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 ببینید\&. یک \f3field-description\fR اختیاری باید معنای فیلد را توضیح دهد و مقادیر مجاز را فهرست کند\&. در صورت نیاز، توضیحات می‌تواند چندین خط را در بر بگیرد\&. داکلت استاندارد (standard doclet) این اطلاعات را به صفحه فرم سریال‌سازی‌شده اضافه می‌کند\&. بخش «صفحات ارجاع متقابل» (Cross-Reference Pages) را ببینید\&. اگر یک فیلد قابل‌سریال‌سازی پس از قابل‌سریال‌سازی شدنِ کلاس به آن افزوده شده باشد، باید عبارتی به توضیحات اصلی آن اضافه شود تا مشخص کند در کدام نسخه افزوده شده است\&. آرگومان‌های \f3include\fR و \f3exclude\fR مشخص می‌کنند که آیا یک کلاس یا بسته باید در صفحه فرم سریال‌سازی‌شده گنجانده شود یا کنار گذاشته شود\&. عملکرد آن‌ها به این صورت است: .RS .TP 0.2i \(bu کلاسی با سطح دسترسی public یا protected که \f3Serializable\fR را پیاده‌سازی می‌کند گنجانده می‌شود، مگر اینکه آن کلاس (یا بسته‌اش) با برچسب \f3@serial exclude\fR علامت‌گذاری شده باشد\&. .TP 0.2i \(bu کلاسی با سطح دسترسی private یا package-private که \f3Serializable\fR را پیاده‌سازی می‌کند کنار گذاشته می‌شود، مگر اینکه آن کلاس (یا بسته‌اش) با برچسب \f3@serial include\fR علامت‌گذاری شده باشد\&. .RE برای مثال، بسته \f3javax\&.swing\fR در package\&.html یا package-info\&.java با برچسب \f3@serial\fR\f3exclude\fR علامت‌گذاری شده است\&. کلاس عمومی \f3java\&.security\&.BasicPermission\fR با برچسب \f3@serial exclude\fR علامت‌گذاری شده است\&. کلاس سطح بسته \f3java\&.util\&.PropertyPermissionCollection\fR با برچسب \f3@serial include\fR علامت‌گذاری شده است\&. برچسب \f3@serial\fR در سطح کلاس، برچسب \f3@serial\fR در سطح بسته را بازنویسی (override) می‌کند\&. .TP @serialData \fIdata-description\fR معرفی‌شده در JDK 1\&.2 از مقدار شرح داده (data description) برای مستندسازی انواع و ترتیب داده‌ها در فرم سریال‌سازی‌شده استفاده می‌کند\&. این داده‌ها شامل داده‌های اختیاری نوشته‌شده توسط متد \f3writeObject\fR و تمام داده‌های (از جمله کلاس‌های پایه) نوشته‌شده توسط متد \f3Externalizable\&.writeExternal\fR می‌شود\&. برچسب \f3@serialData\fR می‌تواند در توضیحات مستندسازی برای متدهای \f3writeObject\fR، \f3readObject\fR، \f3writeExternal\fR، \f3readExternal\fR، \f3writeReplace\fR و \f3readResolve\fR استفاده شود\&. .TP @serialField \fIfield-name\fR\fIfield-type\fR\fIfield-description\fR معرفی‌شده در JDK 1\&.2 یک مؤلفه \f3ObjectStreamField\fR از عضو \f3serialPersistentFields\fR یک کلاس \f3Serializable\fR را مستند می‌کند\&. برای هر مؤلفه \f3ObjectStreamField\fR از یک برچسب \f3@serialField\fR استفاده کنید\&. .TP @since \fIsince-text\fR معرفی‌شده در JDK 1\&.1 یک عنوان \fISince\fR با مقدار مشخص‌شده در \f3since-text\fR به مستندات تولیدشده اضافه می‌کند\&. این متن ساختار داخلی خاصی ندارد\&. این برچسب در هرگونه توضیحات مستندسازی معتبر است: بررسی اجمالی (overview)، بسته، کلاس، رابط، سازنده، متد یا فیلد\&. این برچسب بدین معناست که این تغییر یا ویژگی از زمان انتشار نرم‌افزاری که با مقدار \f3since-text\fR مشخص شده وجود داشته است، برای مثال: \f3@since 1\&.5\fR\&. برای کد مبدأ پلتفرم جاوا، برچسب \f3@since\fR نشان‌دهنده نسخه مشخصات API پلتفرم جاوا است، که لزوماً زمان اضافه شدن کد مبدأ به پیاده‌سازی مرجع نیست\&. استفاده از چند برچسب \f3@since\fR مجاز است و مشابه چند برچسب \f3@author\fR با آن‌ها رفتار می‌شود\&. در صورتی که عنصر برنامه توسط بیش از یک API استفاده شده باشد، می‌توانید از چندین برچسب استفاده کنید\&. .TP @throws \fIclass-name\fR\fIdescription\fR معرفی‌شده در JDK 1\&.2 مشابه برچسب \f3@exception\fR عمل می‌کند\&. بخش @throws را در «نحوه نگارش توضیحات مستندسازی برای ابزار Javadoc» در http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137868\&.html#@exception ببینید\&. برچسب \f3@throws\fR یک زیرعنوان \fIThrows\fR را همراه با متن‌های \f3class-name\fR و \f3description\fR به مستندات تولیدشده اضافه می‌کند\&. مقدار \fIclass-name\fR نام استثنایی است که ممکن است توسط متد پرتاب شود\&. این برچسب تنها در توضیحات مستندسازیِ یک متد یا سازنده معتبر است\&. اگر این کلاس به‌طور کامل مشخص نشده باشد، دستور \f3javadoc\fR از ترتیب جستجو برای یافتن این کلاس استفاده می‌کند\&. می‌توان از چندین برچسب \f3@throws\fR در یک توضیح مستندسازیِ مشخص برای استثناهای یکسان یا متفاوت استفاده کرد\&. بخش «ترتیب جستجو برای برچسب @see» را ببینید\&. برای اطمینان از اینکه تمامی استثناهای بررسی‌شده (checked exceptions) مستند شده‌اند، زمانی که برچسب \f3@throws\fR برای یک استثنا در عبارت throws وجود نداشته باشد، دستور \f3javadoc\fR آن استثنا را (بدون شرح) به خروجی HTML اضافه می‌کند، گویی که با برچسب \f3@throws\fR مستندسازی شده باشد\&. مستندات \f3@throws\fR تنها زمانی از یک متد بازنویسی‌شده (overridden) به یک زیرکلاس کپی می‌شود که استثنا به‌طور صریح در متد بازنویسی‌شده اعلان شده باشد\&. همین امر برای کپی کردن از متد یک رابط به متد پیاده‌سازی‌کننده نیز صدق می‌کند\&. می‌توانید از برچسب \f3{@inheritDoc}\fR برای وادار کردن برچسب \f3@throws\fR به ارث‌بری مستندات استفاده کنید\&. .TP {@value \fIpackage\&.class#field\fR} معرفی‌شده در JDK 1\&.4 مقادیر ثابت را نمایش می‌دهد\&. هنگامی که برچسب \f3{@value}\fR بدون آرگومان در توضیحات مستندسازیِ یک فیلد ایستا (static) استفاده شود، مقدار آن ثابت را نمایش می‌دهد: .sp .nf \f3/**\fP .fi .nf \f3 * The value of this constant is {@value}\&.\fP .fi .nf \f3 */\fP .fi .nf \f3public static final String SCRIPT_START = "<script>"\fP .fi .nf \f3\fP .fi .sp هنگامی که با آرگومان \f3package\&.class#field\fR در هر توضیح مستندسازی استفاده شود، برچسب \f3{@value}\fR مقدار ثابت مشخص‌شده را نمایش می‌دهد: .sp .nf \f3/**\fP .fi .nf \f3 * Evaluates the script starting with {@value #SCRIPT_START}\&.\fP .fi .nf \f3 */\fP .fi .nf \f3public String evalScript(String script) {}\fP .fi .nf \f3\fP .fi .sp آرگومان \f3package\&.class#field\fR شکلی مشابه با آرگومان برچسب \f3@see\fR به خود می‌گیرد، با این تفاوت که عضو مربوطه باید یک فیلد ایستا باشد\&. مقادیر این ثابت‌ها همچنین در بخش Constant Field Values در http://docs\&.oracle\&.com/javase/8/docs/api/constant-values\&.html نمایش داده می‌شوند\&..TP @version \fIversion-text\fR در JDK 1\&.0 معرفی شد\&. هنگامی که از گزینهٔ \f3-version\fR استفاده شود، یک زیرعنوان \fIVersion\fR با مقدار مشخص‌شدهٔ \f3version-text\fR به اسناد تولیدشده اضافه می‌کند\&. این برچسب برای نگهداری شمارهٔ انتشار فعلی نرم‌افزاری که این کد بخشی از آن است در نظر گرفته شده است، برخلاف برچسب \f3@since\fR که شمارهٔ انتشاری را نگه می‌دارد که این کد در آن معرفی شده بود\&. مقدار \f3version-text\fR ساختار داخلی خاصی ندارد\&. بخش @version را در «How to Write Doc Comments for the Javadoc Tool» در http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137868\&.html#@version ببینید\&. یک کامنت مستندسازی می‌تواند شامل چند برچسب \f3@version\fR باشد\&. در صورت لزوم، می‌توانید برای هر برچسب \f3@version\fR یک شمارهٔ انتشار یا برای هر برچسب چند شمارهٔ انتشار مشخص کنید\&. در حالت اول، دستور \f3javadoc\fR یک کاما (,) و یک فاصله بین نام‌ها درج می‌کند\&. در حالت دوم، کل متن بدون تجزیه شدن در سند تولیدشده کپی می‌شود\&. بنابراین، هنگامی که می‌خواهید جداکننده‌ای بومی‌سازی‌شده به‌جز کاما داشته باشید، می‌توانید چندین نام را در هر خط استفاده کنید\&. .SH "محل استفاده از برچسب‌ها (WHERE TAGS CAN BE USED)" بخش‌های زیر توضیح می‌دهند که برچسب‌ها در کجا قابل استفاده هستند\&. توجه داشته باشید که برچسب‌های زیر می‌توانند در تمامی کامنت‌های مستندسازی استفاده شوند: \f3@see\fR، \f3@since\fR، \f3@deprecated\fR، \f3{@link}\fR، \f3{@linkplain}\fR و \f3{@docroot}\fR\&. .SS "برچسب‌های نمای کلی (OVERVIEW TAGS)" برچسب‌های نمای کلی برچسب‌هایی هستند که می‌توانند در کامنت مستندسازیِ صفحهٔ مرور کلی ظاهر شوند (که معمولاً در فایل منبعی با نام overview\&.html قرار دارد)\&. مشابه هر کامنت مستندسازی دیگر، این برچسب‌ها باید پس از توضیحات اصلی قرار گیرند\&. .PP \fIنکته:\fR برچسب \f3{@link}\fR در اسناد نمای کلی در Java SE 1\&.2 دارای باگ است\&. متن به‌درستی ظاهر می‌شود اما پیوندی ندارد\&. برچسب \f3{@docRoot}\fR در حال حاضر در اسناد نمای کلی کار نمی‌کند\&. .PP برچسب‌های نمای کلی به شرح زیر هستند: .PP @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} || .SS "برچسب‌های بسته (PACKAGE TAGS)" برچسب‌های بسته برچسب‌هایی هستند که می‌توانند در کامنت مستندسازی برای یک بسته ظاهر شوند، که در فایل منبع با نام package\&.html یا package-info\&.java قرار دارد\&. برچسب \f3@serial\fR در اینجا تنها با آرگومان \f3include\fR یا \f3exclude\fR قابل استفاده است\&. .PP برچسب‌های بسته به شرح زیر هستند: .PP @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} || .SS "برچسب‌های کلاس و واسط (CLASS AND INTERFACE TAGS)" موارد زیر برچسب‌هایی هستند که می‌توانند در کامنت مستندسازی برای یک کلاس یا واسط ظاهر شوند\&. برچسب \f3@serial\fR درون مستندات یک کلاس یا واسط تنها با یک آرگومان \f3include\fR یا \f3exclude\fR قابل استفاده است\&. .PP @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} || .PP مثال کامنت کلاس: .sp .nf \f3/**\fP .fi .nf \f3 * A class representing a window on the screen\&.\fP .fi .nf \f3 * For example:\fP .fi .nf \f3 * <pre>\fP .fi .nf \f3 * Window win = new Window(parent);\fP .fi .nf \f3 * win\&.show();\fP .fi .nf \f3 * </pre>\fP .fi .nf \f3 *\fP .fi .nf \f3 * @author Sami Shaio\fP .fi .nf \f3 * @version 1\&.13, 06/08/06\fP .fi .nf \f3 * @see java\&.awt\&.BaseWindow\fP .fi .nf \f3 * @see java\&.awt\&.Button\fP .fi .nf \f3 */\fP .fi .nf \f3class Window extends BaseWindow {\fP .fi .nf \f3 \&.\&.\&.\fP .fi .nf \f3}\fP .fi .nf \f3\fP .fi .sp .SS "برچسب‌های فیلد (FIELD TAGS)" این برچسب‌ها می‌توانند در فیلدها ظاهر شوند: .PP @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} .PP مثال کامنت فیلد: .sp .nf \f3 /**\fP .fi .nf \f3 * The X\-coordinate of the component\&.\fP .fi .nf \f3 *\fP .fi .nf \f3 * @see #getLocation()\fP .fi .nf \f3 */\fP .fi .nf \f3 int x = 1263732;\fP .fi .nf \f3\fP .fi .sp .SS "برچسب‌های سازنده و متد (CONSTRUCTOR AND METHOD TAGS)" برچسب‌های زیر می‌توانند در کامنت مستندسازی برای یک سازنده یا یک متد ظاهر شوند، به‌جز برچسب \f3@return\fR که نمی‌تواند در یک سازنده ظاهر شود، و برچسب \f3{@inheritDoc}\fR که دارای محدودیت‌هایی است\&. .PP @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} .PP \fIنکته:\fR برچسب \f3@serialData\fR تنها می‌تواند در کامنت مستندسازی برای متدهای \f3writeObject\fR، \f3readObject\fR، \f3writeExternal\fR، \f3readExternal\fR، \f3writeReplace\fR و \f3readResolve\fR استفاده شود\&. .PP مثال کامنت متد: .sp .nf \f3/**\fP .fi .nf \f3 * Returns the character at the specified index\&. An index \fP .fi .nf \f3 * ranges from <code>0</code> to <code>length() \- 1</code>\fP .fi .nf \f3 *\fP .fi .nf \f3 * @param index the index of the desired character\&.\fP .fi .nf \f3 * @return the desired character\&.\fP .fi .nf \f3 * @exception StringIndexOutOfRangeException \fP .fi .nf \f3 * if the index is not in the range <code>0</code> \fP .fi .nf \f3 * to <code>length()\-1</code>\fP .fi .nf \f3 * @see java\&.lang\&.Character#charValue()\fP .fi .nf \f3 */\fP .fi .nf \f3 public char charAt(int index) {\fP .fi .nf \f3 \&.\&.\&.\fP .fi .nf \f3 }\fP .fi .nf \f3\fP .fi .sp.SH "گزینه‌ها (OPTIONS)" دستور \f3javadoc\fR از داکلت‌ها (doclets) برای تعیین خروجی خود استفاده می‌کند\&. دستور \f3javadoc\fR از داکلت استاندارد پیش‌فرض استفاده می‌کند، مگر اینکه با گزینهٔ \f3-doclet\fR یک داکلت سفارشی تعیین شده باشد\&. دستور \f3javadoc\fR مجموعه‌ای از گزینه‌های خط فرمان را ارائه می‌دهد که می‌توان با هر داکلتی از آن‌ها استفاده کرد\&. این گزینه‌ها در «گزینه‌های Javadoc» شرح داده شده‌اند\&. داکلت استاندارد مجموعهٔ دیگری از گزینه‌های خط فرمان را فراهم می‌کند که در «گزینه‌های داکلت استاندارد» شرح داده شده‌اند\&. نام تمامی گزینه‌ها به بزرگ و کوچک بودن حروف حساس نیست، اما آرگومان‌های آن‌ها به حروف بزرگ و کوچک حساس هستند\&. .TP 0.2i \(bu همچنین ببینید: گزینه‌های Javadoc .TP 0.2i \(bu همچنین ببینید: گزینه‌های داکلت استاندارد .PP گزینه‌ها عبارتند از: .PP -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\efilename || -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 .PP گزینه‌های زیر، گزینه‌های اصلی Javadoc هستند که برای تمام داکلت‌ها در دسترس می‌باشند\&. داکلت استاندارد باقی موارد را ارائه می‌دهد: \f3-bootclasspath\fR، \f3-breakiterator\fR، \f3-classpath\fR، \f3-doclet\fR، \f3-docletpath\fR، \f3-encoding\fR، -\f3exclude\fR، \f3-extdirs\fR، \f3-help\fR، \f3-locale\fR، \f3-\fR\f3overview\fR، \f3-package\fR، \f3-private\fR، \f3-protected\fR، \f3-public\fR، \f3-quiet\fR، \f3-source\fR، \f3-sourcepath\fR، \f3-subpackages\fR و \f3-verbose\fR\&. .SS "گزینه‌های JAVADOC (JAVADOC OPTIONS)" .TP -overview \fIpath/filename\fR .br مشخص می‌کند که دستور \f3javadoc\fR باید متن مستندات کلی (overview) را از فایل مبدأ مشخص‌شده توسط \fIpath/filename\fR واکشی کرده و آن را در صفحهٔ Overview (فایل overview-summary\&.html) قرار دهد\&. مسیر \fIpath/filename\fR نسبت به دایرکتوری جاری سنجیده می‌شود\&. اگرچه می‌توانید از هر نام دلخواهی برای مقدار \f3filename\fR استفاده کنید و آن را در هر کجای مسیر قرار دهید، اما معمول است که نام آن را overview\&.html بگذارید و آن را در درخت مبدأ درون دایرکتوری‌ای قرار دهید که شامل بالاترین دایرکتوری‌های بسته است\&. در این مکان، هنگام مستندسازی بسته‌ها به هیچ مسیری نیاز نیست، زیرا گزینهٔ \f3-sourcepath\fR به این فایل اشاره می‌کند\&. برای مثال، اگر درخت مبدأ برای بستهٔ \f3java\&.lang\fR برابر با /src/classes/java/lang/ باشد، می‌توانید فایل overview را در /src/classes/overview\&.html قرار دهید\&. بخش Real-World Examples را ببینید\&. برای اطلاعات دربارهٔ فایل مشخص‌شده با \fIpath/filename\fR، بخش Overview Comment Files را ببینید\&. صفحهٔ overview تنها زمانی ایجاد می‌شود که دو یا چند نام بسته را به دستور \f3javadoc\fR ارسال کنید\&. برای توضیحات بیشتر، بخش HTML Frames را ببینید\&. عنوان صفحهٔ overview توسط \f3-doctitle\fR تنظیم می‌شود\&. .TP -Xdoclint:(all|none|[-]\fI<group>\fR) .br هشدارهایی را برای ارجاعات نادرست، عدم دسترس‌پذیری (accessibility) و کامنت‌های مفقود Javadoc گزارش می‌کند، و خطاهایی را برای نحو (syntax) نامعتبر Javadoc و برچسب‌های مفقود HTML گزارش می‌دهد\&. این گزینه به دستور \f3javadoc\fR امکان می‌دهد تمام کامنت‌های مستنداتی گنجانده‌شده در خروجی تولیدشده را بررسی کند\&. طبق معمول، می‌توانید با گزینه‌های استاندارد \f3-public\fR، \f3-protected\fR، \f3-package\fR و \f3-private\fR مواردی را که باید در خروجی تولیدشده قرار گیرند انتخاب کنید\&. هنگامی که \f3-Xdoclint\fR فعال باشد، مشکلات را با پیام‌هایی مشابه با دستور \f3javac\fR گزارش می‌دهد\&. دستور \f3javadoc\fR یک پیام، رونوشتی از خط مبدأ و یک علامت هشتک (caret) چاپ می‌کند که به موقعیت دقیق خطای شناسایی‌شده اشاره دارد\&. پیام‌ها بسته به شدت مشکل و احتمال ایجاد خطا در صورت اعتبارسنجی مستندات تولیدشده توسط یک validator، ممکن است هشدار یا خطا باشند\&. برای نمونه، ارجاعات نادرست یا کامنت‌های مفقود Javadoc باعث نمی‌شوند که دستور \f3javadoc\fR کدهای HTML نامعتبر تولید کند، بنابراین این موارد به عنوان هشدار گزارش می‌شوند\&. خطاهای نحوی یا برچسب‌های پایانی مفقود در HTML باعث می‌شوند که دستور \f3javadoc\fR خروجی نامعتبر تولید کند، بنابراین این موارد به عنوان خطا گزارش می‌شوند\&. به‌طور پیش‌فرض، گزینهٔ \f3-Xdoclint\fR فعال است\&. آن را با گزینهٔ \f3-Xdoclint:none\fR غیرفعال کنید\&. آنچه را که گزینهٔ \f3-Xdoclint\fR گزارش می‌دهد با گزینه‌های زیر تغییر دهید: .RS .TP 0.2i \(bu \f3-Xdoclint none\fR : غیرفعال کردن گزینهٔ \f3-Xdoclint\fR .TP 0.2i \(bu \f3-Xdoclint\fR\fIgroup\fR : فعال کردن بررسی‌های \fIgroup\fR .TP 0.2i \(bu \f3-Xdoclint all\fR : فعال کردن تمام گروه‌های بررسی .TP 0.2i \(bu \f3-Xdoclint all,\fR\fI-group\fR : فعال کردن همهٔ بررسی‌ها به جز \fIgroup\fR .RE متغیر \fIgroup\fR یکی از مقادیر زیر را می‌پذیرد: .RS .TP 0.2i \(bu \f3accessibility\fR : بررسی مشکلاتی که توسط یک ابزار ارزیابی دسترس‌پذیری شناسایی می‌شوند (برای نمونه، عدم تعیین مشخصه‌های caption یا summary در یک برچسب \f3<table>\fR)\&. .TP 0.2i \(bu \f3html\fR : شناسایی مشکلات سطح بالای HTML، مانند قرار دادن عناصر بلوکی درون عناصر درون‌خطی (inline)، یا نبستن عناصری که نیازمند برچسب پایانی هستند\&. این قواعد از مشخصات HTML 4\&.01 برگرفته شده‌اند\&. این نوع بررسی دستور \f3javadoc\fR را قادر می‌سازد مشکلات HTML را که ممکن است بسیاری از مرورگرها نادیده بگیرند، شناسایی کند\&. .TP 0.2i \(bu \f3missing\fR : بررسی کامنت‌ها یا تگ‌های مفقود Javadoc (برای نمونه، کامنت یا کلاس مفقود، یا یک تگ مفقود \f3@return\fR یا تگ مشابه روی یک متد)\&. .TP 0.2i \(bu \f3reference\fR : بررسی مشکلات مربوط به ارجاعات به عناصر Java API از برچسب‌های Javadoc (برای نمونه، آیتم یافت‌نشده در \f3@see\fR، یا نام نادرست پس از \f3@param)\fR\&. .TP 0.2i \(bu \f3syntax\fR : بررسی مشکلات سطح پایین مانند براکت‌های شکسته فرارنیافته (\f3<\fR و \f3>\fR) و علامت‌های امپرسند (\f3&\fR) و برچسب‌های نامعتبر Javadoc\&. .RE می‌توانید گزینهٔ \f3-Xdoclint\fR را چندین بار مشخص کنید تا بررسی خطاها و هشدارها در چند دسته فعال شود\&. همچنین، می‌توانید چندین دستهٔ خطا و هشدار را با استفاده از گزینه‌های پیش‌گفته مشخص کنید\&. برای مثال، از هر یک از دستورهای زیر برای بررسی مشکلات HTML، نحو و دسترس‌پذیری در فایل \fIfilename\fR استفاده کنید\&. .sp .nf \f3javadoc \-Xdoclint:html \-Xdoclint:syntax \-Xdoclint:accessibility \fIfilename\fR\fP .fi .nf \f3javadoc \-Xdoclint:html,syntax,accessibility \fIfilename\fR\fP .fi .nf \f3\fP .fi .sp \fIنکته:\fR دستور \f3javadoc\fR جامعیت این بررسی‌ها را تضمین نمی‌کند\&. به‌ویژه، این ابزار یک بررسی‌کنندهٔ کامل تطابق با HTML نیست\&. هدف گزینهٔ \f3-Xdoclint\fR این است که دستور \f3javadoc\fR را قادر سازد بخش عمده‌ای از خطاهای رایج را گزارش کند\&. دستور \f3javadoc\fR تلاشی برای اصلاح ورودی نامعتبر نمی‌کند، بلکه صرفاً آن را گزارش می‌دهد\&. .TP -public .br تنها کلاس‌ها و اعضای public را نشان می‌دهد\&. .TP -protected .br تنها کلاس‌ها و اعضای protected و public را نشان می‌دهد\&. این حالت پیش‌فرض است\&. .TP -package .br تنها کلاس‌ها و اعضای package، protected و public را نشان می‌دهد\&. .TP -private .br تمام کلاس‌ها و اعضا را نشان می‌دهد\&. .TP -help .br راهنمای برخط را نمایش می‌دهد که تمام گزینه‌های خط فرمان \f3javadoc\fR و \f3doclet\fR را فهرست می‌کند\&. .TP -doclet \fIclass\fR .br فایل کلاسی را مشخص می‌کند که داکلتِ مورد استفاده در تولید مستندات را راه‌اندازی می‌کند\&. از نام کاملاً مشخص (fully qualified name) استفاده کنید\&. این داکلت محتوا را تعیین کرده و خروجی را قالب‌بندی می‌کند\&. اگر از گزینهٔ \f3-doclet\fR استفاده نشود، دستور \f3javadoc\fR از داکلت استاندارد برای تولید قالب پیش‌فرض HTML استفاده می‌کند\&. این کلاس باید شامل متد \f3start(Root)\fR باشد\&. مسیر رسیدن به این کلاس آغازین توسط گزینهٔ \f3-docletpath\fR تعیین می‌شود\&. بخش Doclet Overview را در http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/doclet/overview\&.html ببینید\&. .TP -docletpath \fIclasspathlist\fR .br مسیر فایل کلاس آغازین داکلت (مشخص‌شده با گزینهٔ \f3-doclet\fR) و هر فایل JAR که به آن وابسته است را مشخص می‌کند\&. اگر فایل کلاس آغازین درون یک فایل JAR باشد، این گزینه مسیر منتهی به آن فایل JAR را مشخص می‌کند\&. می‌توانید یک مسیر مطلق یا مسیری نسبت به دایرکتوری جاری مشخص کنید\&. اگر \f3classpathlist\fR شامل چندین مسیر یا فایل JAR باشد، باید آن‌ها را در Oracle Solaris با دونقطه (:) و در Windows با نقطه‌ویرگول (;) از یکدیگر جدا کرد\&. زمانی که کلاس آغازین داکلت از قبل در مسیر جست‌وجو قرار داشته باشد، نیازی به این گزینه نیست\&. بخش Doclet Overview را در http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/doclet/overview\&.html ببینید\&. .TP -1\&.1 .br از Javadoc 1\&.4 بدون هیچ جایگزینی حذف شده است\&. این گزینه مستنداتی با ظاهر و قابلیت‌های مستندات تولیدشده توسط Javadoc 1\&.1 ایجاد می‌کرد (این گزینه هرگز از کلاس‌های تودرتو پشتیبانی نکرد)\&. اگر به این گزینه نیاز دارید، به جای آن از Javadoc 1\&.2 یا 1\&.3 استفاده کنید\&. .TP -source \fIrelease\fR .br نسخهٔ کد منبع پذیرفته‌شده را مشخص می‌کند\&. مقادیر زیر برای پارامتر \f3release\fR مجاز هستند\&. از مقدار \f3release\fR متناظر با مقداری که هنگام کامپایل کد با دستور \f3javac\fR استفاده می‌کنید بهره ببرید\&. .RS .TP 0.2i \(bu \fIمقدار انتشار: 1\&.5\fR\&. دستور \f3javadoc\fR کدهای شامل جنریک‌ها (generics) و سایر ویژگی‌های زبان معرفی‌شده در JDK 1\&.5 را می‌پذیرد\&. هنگامی که از گزینهٔ \f3-source\fR استفاده نشود، کامپایلر رفتار 1\&.5 را به‌طور پیش‌فرض در نظر می‌گیرد\&. .TP 0.2i \(bu \fIمقدار انتشار: 1\&.4\fR\&. دستور \f3javadoc\fR کدهای شامل assertionها را که در JDK 1\&.4 معرفی شدند می‌پذیرد\&. .TP 0.2i \(bu \fIمقدار انتشار: 1\&.3\fR\&. دستور \f3javadoc\fR از assertionها، جنریک‌ها یا سایر ویژگی‌های زبان معرفی‌شده پس از JDK 1\&.3 پشتیبانی نمی‌کند\&. .RE .TP -sourcepath \fIsourcepathlist\fR .br مسیرهای جست‌وجو را برای یافتن فایل‌های مبدأ هنگام ارسال نام بسته‌ها یا گزینهٔ \f3-subpackages\fR به دستور \f3javadoc\fR مشخص می‌کند\&. چندین مسیر را با دونقطه (:) از یکدیگر جدا کنید\&. دستور \f3javadoc\fR تمام زیردایرکتوری‌های مسیرهای مشخص‌شده را جست‌وجو می‌کند\&. توجه داشته باشید که این گزینه نه تنها برای یافتن محل فایل‌های مبدأ در حال مستندسازی، بلکه برای یافتن فایل‌های مبدأیی که مستندسازی نمی‌شوند اما کامنت‌های آن‌ها توسط فایل‌های مبدأ تحت مستندسازی به ارث برده می‌شود نیز به کار می‌رود\&. تنها زمانی می‌توانید از گزینهٔ \f3-sourcepath\fR استفاده کنید که نام بسته‌ها را به دستور \f3javadoc\fR ارسال می‌کنید\&. این گزینه فایل‌های مبدأ ارائه‌شده به دستور \f3javadoc\fR را مکان‌یابی نمی‌کند\&. برای مشخص کردن محل فایل‌های مبدأ، به آن دایرکتوری بروید یا همان‌طور که در بخش Document One or More Classes نشان داده شده است، مسیر را قبل از هر فایل درج کنید\&. اگر \f3-sourcepath\fR را نادیده بگیرید، دستور \f3javadoc\fR از مسیر کلاس برای یافتن فایل‌های مبدأ استفاده می‌کند (به \f3-classpath\fR مراجعه کنید)\&. مقدار پیش‌فرض \f3-sourcepath\fR همان مقدار مسیر کلاس (class path) است\&. اگر \f3-classpath\fR درج نشود و نام بسته‌ها را به دستور \f3javadoc\fR ارسال کنید، دستور \f3javadoc\fR در دایرکتوری جاری و زیردایرکتوری‌های آن به جست‌وجوی فایل‌های مبدأ می‌پردازد\&. مقدار \f3sourcepathlist\fR را روی دایرکتوری ریشهٔ درخت مبدأ برای بسته‌ای که مستند می‌کنید قرار دهید\&. برای مثال، فرض کنید می‌خواهید بسته‌ای با نام \f3com\&.mypackage\fR را مستندسازی کنید که فایل‌های مبدأ آن در مسیر /home/user/src/com/mypackage/*\&.java قرار دارند\&. مقدار sourcepath را برابر با /home/user/src (دایرکتوری شامل com\emypackage) تعیین کرده و سپس نام بسته را به‌صورت زیر ارائه دهید: .sp .nf \f3javadoc \-sourcepath /home/user/src/ com\&.mypackage\fP .fi .nf \f3\fP .fi .sp توجه داشته باشید که اگر مقدار sourcepath و نام بسته را به هم متصل کنید و نقطه را به یک اسلش (/) تغییر دهید، مسیر کامل منتهی به بسته را خواهید داشت: /home/user/src/com/mypackage برای اشاره به دو مسیر مبدأ: .sp .nf \f3javadoc \-sourcepath /home/user1/src:/home/user2/src com\&.mypackage\fP .fi .nf \f3\fP .fi .sp .TP -classpath \fIclasspathlist\fR .br مسیرهایی را مشخص می‌کند که دستور \f3javadoc\fR در آن‌ها به دنبال کلاس‌های ارجاع‌شده می‌گردد\&. این‌ها کلاس‌های مستندشده به‌علاوهٔ هر کلاسی هستند که توسط آن کلاس‌ها ارجاع داده شده‌اند\&. چندین مسیر را با دونقطه (:) جدا کنید\&. دستور \f3javadoc\fR تمام زیردایرکتوری‌های مسیرهای مشخص‌شده را جست‌وجو می‌کند\&. برای تعیین مقدار \f3classpathlist\fR، از دستورالعمل‌های موجود در مستندات مسیر کلاس (class path) پیروی کنید\&. اگر \f3-sourcepath\fR را نادیده بگیرید، دستور \f3javadoc\fR از \f3-classpath\fR برای یافتن فایل‌های مبدأ و فایل‌های کلاس استفاده می‌کند (جهت سازگاری با نسخه‌های پیشین)\&. اگر می‌خواهید فایل‌های مبدأ و کلاس را در مسیرهای جداگانه جست‌وجو کنید، از هر دو گزینهٔ \f3-sourcepath\fR و \f3-classpath\fR استفاده نمایید\&. برای مثال، اگر می‌خواهید \f3com\&.mypackage\fR را مستندسازی کنید که فایل‌های مبدأ آن در دایرکتوری /home/user/src/com/mypackage قرار دارند، و این بسته به کتابخانه‌ای در /home/user/lib وابسته است، از دستور زیر استفاده کنید: .sp .nf \f3javadoc \-sourcepath /home/user/lib \-classpath /home/user/src com\&.mypackage\fP .fi .nf \f3\fP .fi .sp مشابه سایر ابزارها، اگر \f3-classpath\fR را مشخص نکنید، دستور \f3javadoc\fR در صورت تنظیم بودن متغیر محیطی \f3CLASSPATH\fR از آن استفاده می‌کند\&. اگر هیچ‌یک تنظیم نشده باشند، دستور \f3javadoc\fR به دنبال کلاس‌ها در دایرکتوری جاری می‌گردد\&. برای شرح دقیق نحوهٔ استفادهٔ دستور \f3javadoc\fR از \f3-classpath\fR برای یافتن کلاس‌های کاربر در ارتباط با کلاس‌های افزونه (extension) و کلاس‌های خودراه‌انداز (bootstrap)، بخش How Classes Are Found را در http://docs\&.oracle\&.com/javase/8/docs/technotes/tools/findingclasses\&.html ببینید\&. عنصری در مسیر کلاس که شامل نام پایهٔ * باشد، معادل تعیین فهرستی از تمام فایل‌های درون آن دایرکتوری با پسوند \f3\&.jar\fR یا \f3\&.JAR\fR در نظر گرفته می‌شود\&. برای مثال، اگر دایرکتوری \f3mydir\fR حاوی \f3a\&.jar\fR و \f3b\&.JA\fRR باشد، عنصر مسیر کلاس \f3foo/*\fR به \f3A\&.jar:b\&.JAR\fR بسط داده می‌شود، جز اینکه ترتیب فایل‌های JAR نامشخص است\&. تمام فایل‌های JAR درون دایرکتوری مشخص‌شده، از جمله فایل‌های پنهان، در این فهرست قرار می‌گیرند\&. یک مدخل در مسیر کلاس که شامل * باشد، به فهرستی از تمام فایل‌های jar در دایرکتوری جاری بسط می‌یابد\&. متغیر محیطی \f3CLASSPATH\fR نیز به همین صورت بسط داده می‌شود\&. هرگونه بسط نویسه‌های عام (wildcard) در مسیر کلاس قبل از شروع به کار ماشین مجازی جاوا (JVM) رخ می‌دهد\&. هیچ برنامهٔ جاوایی هرگز نویسه‌های عام بسط‌نیافته را نمی‌بیند مگر از طریق پرس‌وجو از محیط، برای نمونه با فراخوانی System\&.getenv(\f3"CLASSPATH"\fR)\&..TP -subpackages \fIpackage1:package2:\&.\&.\&.\fR .br مستندات را از فایل‌های منبع در بسته‌های مشخص‌شده و به‌صورت بازگشتی در زیربسته‌های آن‌ها تولید می‌کند\&. این گزینه زمانی که زیربسته‌های جدیدی را به کد منبع اضافه می‌کنید مفید است، زیرا آن‌ها به‌طور خودکار گنجانده می‌شوند\&. هر آرگومان بسته، هر زیربستهٔ سطح بالا (مانند \f3java\fR) یا یک بستهٔ کامل (مانند \f3javax\&.swing\fR) است که نیازی به داشتن فایل‌های منبع ندارد\&. آرگومان‌ها در تمام سیستم‌های عامل با دونقطه (:) از یکدیگر جدا می‌شوند\&. نویسه‌های عام (Wild cards) مجاز نیستند\&. از \f3-sourcepath\fR برای مشخص کردن محل یافتن بسته‌ها استفاده کنید\&. این گزینه فایل‌های منبعی را که در درخت منبع قرار دارند اما متعلق به بسته‌ها نیستند پردازش نمی‌کند\&. بخش Process Source Files را ببینید\&. برای مثال، دستور زیر مستندات مربوط به بسته‌هایی با نام \f3java\fR و \f3javax\&.swing\fR و تمام زیربسته‌های آن‌ها را تولید می‌کند\&. .sp .nf \f3javadoc \-d docs \-sourcepath /home/user/src \-subpackages java:javax\&.swing \fP .fi .nf \f3\fP .fi .sp .TP -exclude \fIpackagename1:packagename2:\&.\&.\&.\fR .br به‌طور قطعی و بی‌قیدوشرط، بسته‌های مشخص‌شده و زیربسته‌های آن‌ها را از فهرستی که توسط \f3-subpackages\fR ساخته شده مستثنی می‌کند\&. این گزینه آن بسته‌ها را حتی در صورتی که توسط گزینهٔ \f3-subpackages\fR پیشین یا پسین دیگری گنجانده شده باشند، حذف می‌کند\&. مثال زیر بسته‌های \f3java\&.io\fR، \f3java\&.util\fR و \f3java\&.math\fR (در کنار سایر بسته‌ها) را شامل می‌شود، اما بسته‌هایی را که ریشه در \f3java\&.net\fR و \f3java\&.lang\fR دارند مستثنی می‌سازد\&. توجه داشته باشید که این مثال \f3java\&.lang\&.ref\fR را که یک زیربسته از \f3java\&.lang\fR است، مستثنی می‌کند\&. .sp .nf \f3javadoc \-sourcepath /home/user/src \-subpackages java \-exclude \fP .fi .nf \f3 java\&.net:java\&.lang\fP .fi .nf \f3\fP .fi .sp .TP -bootclasspath \fIclasspathlist\fR .br مسیرهایی را مشخص می‌کند که کلاس‌های راه‌اندازی (boot classes) در آن قرار دارند\&. این‌ها معمولاً کلاس‌های پلتفرم جاوا هستند\&. مقدار \f3bootclasspath\fR بخشی از مسیر جستجویی است که دستور \f3javadoc\fR برای جستجوی فایل‌های منبع و فایل‌های کلاس استفاده می‌کند\&. برای اطلاعات بیشتر، بخش How Classes Are Found را در <http://docs\&.oracle\&.com/javase/8/docs/technotes/tools/findingclasses\&.html> ببینید\&. دایرکتوری‌ها را در پارامترهای \f3classpathlist\fR برای Windows با نقطه-ویرگول (;) و برای Oracle Solaris با دونقطه (:) جدا کنید\&. .TP -extdirs \fIdirist\fR .br دایرکتوری‌هایی را مشخص می‌کند که کلاس‌های افزونه (extension classes) در آن قرار دارند\&. این‌ها کلاس‌هایی هستند که از سازوکار افزونه جاوا (Java Extension) بهره می‌برند\&. گزینهٔ \f3extdirs\fR بخشی از مسیر جستجویی است که دستور \f3javadoc\fR برای یافتن فایل‌های منبع و کلاس به کار می‌برد\&. برای اطلاعات بیشتر گزینهٔ \f3-classpath\fR را ببینید\&. دایرکتوری‌ها را در \f3dirlist\fR با نقطه-ویرگول (;) برای Windows و با دونقطه (:) برای Oracle Solaris از هم جدا کنید\&. .TP -verbose .br پیام‌های با جزئیات بیشتری را در هنگام اجرای دستور \f3javadoc\fR ارائه می‌دهد\&. بدون گزینهٔ \f3verbose\fR، پیام‌ها تنها برای بارگذاری فایل‌های منبع، تولید مستندات (یک پیام به ازای هر فایل منبع) و مرتب‌سازی نمایش می‌یابند\&. گزینهٔ verbose موجب چاپ پیام‌های اضافی می‌شود که مدت زمان لازم (به میلی‌ثانیه) را برای تجزیهٔ هر فایل منبع جاوا مشخص می‌کنند\&. .TP -quiet .br پیام‌ها را قطع می‌کند تا فقط هشدارها و خطاها نمایش داده شوند و بررسی آن‌ها آسان‌تر شود\&. این گزینه همچنین رشتهٔ \f3version\fR را پنهان می‌سازد\&. .TP -breakiterator .br از مرز جملهٔ بین‌المللی‌شدهٔ \f3java\&.text\&.BreakIterator\fR برای تعیین انتهای جملهٔ اول در توضیحات اصلی یک بسته، کلاس یا عضو برای زبان انگلیسی استفاده می‌کند\&. سایر محلی‌سازی‌ها از پیش به جای الگوریتم خاص زبان انگلیسی، از کلاس \f3BreakIterator\fR استفاده می‌کنند\&. اولین جمله در خلاصهٔ بسته، کلاس یا عضو و در نمایهٔ الفبایی کپی می‌شود\&. از نسخهٔ JDK 1\&.2 به بعد، کلاس \f3BreakIterator\fR برای تعیین انتهای جمله برای تمام زبان‌ها به جز انگلیسی استفاده می‌شود\&. بنابراین، گزینهٔ \f3-breakiterator\fR از نسخهٔ 1\&.2 به بعد برای هیچ زبانی به جز انگلیسی اثری ندارد\&. زبان انگلیسی الگوریتم پیش‌فرض خاص خود را دارد: .RS .TP 0.2i \(bu الگوریتم پیش‌فرض شکست جمله در انگلیسی\&. در نقطه به‌همراه یک فاصله یا یک برچسب بلوکی HTML مانند \f3<P>\fR متوقف می‌شود\&. .TP 0.2i \(bu الگوریتم شکست جملهٔ Breakiterator\&. در نقطه، علامت سؤال یا علامت تعجب که پس از آن یک فاصله و کلمه‌ای با حرف بزرگ باشد متوقف می‌شود\&. این کار برای پشتیبانی از بیشتر کلمات اختصاری است (مانند "The serial no\&. is valid"، ولی موردی مانند "Mr\&. Smith" را مدیریت نمی‌کند)\&. گزینهٔ \f3-breakiterator\fR روی برچسب‌های HTML یا جملاتی که با اعداد یا نمادها شروع می‌شوند متوقف نمی‌شود\&. الگوریتم در آخرین نقطه در \&.\&./filename، حتی اگر درون یک برچسب HTML باشد، متوقف می‌شود\&. .RE در Java SE 1\&.5 پیام‌های هشدار گزینهٔ \f3-breakiterator\fR حذف شده‌اند و الگوریتم پیش‌فرض شکست جمله بدون تغییر باقی مانده است\&. اگر کد منبع خود را برای حذف هشدارهای گزینهٔ \f3-breakiterator\fR در Java SE 1\&.4\&.x دستکاری نکرده‌اید، نیازی به انجام کاری ندارید\&. این هشدارها از نسخهٔ Java SE 1\&.5\&.0 برطرف شده‌اند\&. .TP -locale \fIlanguage_country_variant\fR .br محلی‌سازی (locale) مورد استفاده توسط دستور \f3javadoc\fR را هنگام تولید مستندات مشخص می‌کند\&. این آرگومان نام locale است، همان‌گونه که در مستندات \f3java\&.util\&.Locale\fR شرح داده شده، مانند \f3en_US\fR (انگلیسی، ایالات متحده) یا \f3en_US_WIN\fR (گونهٔ Windows)\&. \fIنکته:\fR گزینهٔ \f3-locale\fR باید جلوتر (در سمت چپ) تمام گزینه‌های ارائه‌شده توسط doclet استاندارد یا هر doclet دیگری قرار گیرد\&. در غیر این صورت، نوارهای ناوبری به زبان انگلیسی نمایش داده می‌شوند\&. این تنها گزینهٔ خط فرمان است که به ترتیب قرارگیری وابسته است\&. بخش Standard Doclet Options را ببینید\&. تعیین محلی‌سازی موجب می‌شود دستور \f3javadoc\fR فایل‌های منبع (resource files) آن locale را برای پیام‌هایی چون رشته‌های نوار ناوبری، سرتیترهای فهرست‌ها و جدول‌ها، محتوای فایل راهنما، کامنت‌های فایل stylesheet\&.css و غیره برگزیند\&. این گزینه همچنین ترتیب مرتب‌سازی برای فهرست‌های الفبایی و جداکنندهٔ جملات را برای تعیین انتهای اولین جمله مشخص می‌سازد\&. گزینهٔ \f3-locale\fR تعیین‌کنندهٔ locale متن کامنت‌های مستنداتی موجود در فایل‌های منبع کلاس‌های مستندشده نیست\&. .TP -encoding .br نام کدگذاری (encoding) فایل‌های منبع را مشخص می‌کند، مانند \f3EUCJIS/SJIS\fR\&. در صورت عدم تعیین این گزینه، مبدل پیش‌فرض پلتفرم استفاده می‌شود\&. همچنین گزینه‌های \f3-docencoding name\fR و \f3-charset name\fR را ببینید\&. .TP -J\fIflag\fR .br پرچم \f3flag\fR را مستقیماً به محیط زمان اجرای جاوا (JRE) که دستور \f3javadoc\fR را اجرا می‌کند ارسال می‌نماید\&. برای نمونه، اگر بخواهید اطمینان حاصل کنید که سیستم ۳۲ مگابایت حافظه برای پردازش مستندات تولیدشده اختصاص می‌دهد، گزینهٔ \f3-Xmx\fR را بدین صورت فراخوانی می‌کنید: \f3javadoc -J-Xmx32m -J-Xms32m com\&.mypackage\fR\&. توجه داشته باشید که \f3-Xms\fR اختیاری است زیرا صرفاً اندازهٔ حافظهٔ اولیه را تعیین می‌کند، که این ویژگی زمانی که حداقل حافظهٔ مورد نیاز را می‌دانید کاربرد دارد\&. بین \f3J\fR و \f3flag\fR نباید هیچ فاصله‌ای وجود داشته باشد\&. برای اطلاع از نسخهٔ دستور \f3javadoc\fR که از آن استفاده می‌کنید، گزینهٔ \f3-version\fR را به کار ببرید\&. شماره نسخهٔ doclet استاندارد در خروجی آن نمایش می‌یابد\&. بخش Running the Javadoc Command را ببینید\&. .sp .nf \f3javadoc \-J\-version\fP .fi .nf \f3java version "1\&.7\&.0_09"\fP .fi .nf \f3Java(TM) SE Runtime Environment (build 1\&.7\&.0_09\-b05)\fP .fi .nf \f3Java HotSpot(TM) 64\-Bit Server VM (build 23\&.5\-b02, mixed mode)\fP .fi .nf \f3\fP .fi .sp .TP -javafx .br مستندات HTML را با بهره‌گیری از افزونه‌های JavaFX روی doclet استاندارد تولید می‌کند\&. مستندات تولیدشده علاوه بر سایر بخش‌های خلاصهٔ ایجادشده توسط doclet استاندارد جاوا، شامل یک بخش خلاصه ویژگی (Property Summary) نیز خواهد بود\&. ویژگی‌های فهرست‌شده به بخش‌های متدهای getter و setter مربوط به هر ویژگی پیوند دارند\&. اگر کامنت‌های مستنداتی به‌طور صریح برای متدهای getter و setter نوشته نشده باشد، کامنت‌های مستندات متد ویژگی به‌طور خودکار به مستندات تولیدشده برای این متدها رونوشت می‌شود\&. این گزینه همچنین یک برچسب جدید به نام \f3@defaultValue\fR اضافه می‌کند که امکان مستندسازی مقدار پیش‌فرض یک ویژگی را فراهم می‌سازد\&. مثال: .sp .nf \f3javadoc \-javafx MyClass\&.java \-d testdir\fP .fi .sp .SS "گزینه‌های استاندارد DOCLET (STANDARD DOCLET OPTIONS)" .TP -d \fIdirectory\fR .br دایرکتوری مقصدی را مشخص می‌کند که دستور \f3javadoc\fR فایل‌های HTML تولیدشده را در آن ذخیره می‌نماید\&. در صورت حذف گزینهٔ \f3-d\fR، فایل‌ها در دایرکتوری جاری ذخیره می‌شوند\&. مقدار \f3directory\fR می‌تواند مطلق یا نسبت به دایرکتوری کاری فعلی باشد\&. از نسخهٔ Java SE 1\&.4، دایرکتوری مقصد در زمان اجرای دستور \f3javadoc\fR به‌طور خودکار ساخته می‌شود\&. برای مثال، دستور زیر مستندات بستهٔ \f3com\&.mypackage\fR را تولید کرده و نتایج را در دایرکتوری /user/doc/ ذخیره می‌کند: \f3javadoc -d /user/doc/ com\&.mypackage\fR\&. .TP -use .br یک برگهٔ Use (کاربرد) برای هر کلاس و بستهٔ مستندشده ایجاد می‌کند\&. این صفحه مشخص می‌کند که چه بسته‌ها، کلاس‌ها، متدها، سازنده‌ها و فیلدهایی از هر API کلاس یا بستهٔ مشخص‌شده استفاده می‌کنند\&. به عنوان نمونه برای کلاس C، مواردی که از کلاس C استفاده می‌کنند شامل زیرکلاس‌های C، فیلدهای تعریف‌شده از نوع C، متدهایی که مقدار بازگشتی آن‌ها C است و متدها و سازنده‌هایی با پارامترهایی از نوع C خواهد بود\&. برای مثال، می‌توانید به برگهٔ Use برای نوع \f3String\fR نگاه کنید\&. از آنجا که متد \f3getName\fR در کلاس \f3java\&.awt\&.Font\fR نوع \f3String\fR برمی‌گرداند، این متد از \f3String\fR استفاده می‌کند و در نتیجه در برگهٔ Use برای \f3String\fR نمایش می‌یابد\&. این ویژگی تنها استفاده‌ها از API را مستند می‌کند، نه پیاده‌سازی را\&. هنگامی که یک متد در پیاده‌سازی خود از \f3String\fR استفاده می‌کند، اما رشته‌ای به عنوان آرگومان دریافت نکرده یا آن را برنمی‌گرداند، این مورد به عنوان استفاده از \f3String\fR لحاظ نمی‌شود\&. برای دسترسی به صفحهٔ Use تولیدشده، به صفحهٔ کلاس یا بسته رفته و روی پیوند \fIUse\fR در نوار ناوبری کلیک کنید\&. .TP -version .br متن @version را در اسناد تولیدشده قرار می‌دهد\&. این متن به‌طور پیش‌فرض حذف می‌شود\&. برای یافتن نسخهٔ مورد استفادهٔ دستور \f3javadoc\fR، از گزینهٔ \f3-J-version\fR استفاده کنید\&. .TP -author .br متن \f3@author\fR را در اسناد تولیدشده قرار می‌دهد\&. .TP -splitindex .br فایل نمایه را به چندین فایل، بر اساس حروف الفبا، یک فایل برای هر حرف، به‌علاوهٔ یک فایل برای هر مدخل نمایه‌ای که با نمادهای غیرحرفی آغاز می‌شود تقسیم می‌کند\&. .TP -windowtitle \fItitle\fR .br عنوانی را برای قرار گرفتن در برچسب HTML \f3<title>\fR مشخص می‌کند\&. متنی که در برچسب \f3title\fR تعیین می‌شود در عنوان پنجره و در نشانک‌های مرورگر که کاربران برای این صفحه می‌سازند نمایش داده می‌شود\&. این عنوان نباید حاوی برچسب‌های HTML باشد زیرا مرورگر آن‌ها را به‌درستی تفسیر نمی‌کند\&. برای هر علامت نقل‌قول درونی در برچسب \f3title\fR از نویسه‌های گریز (escape) استفاده کنید\&. اگر گزینهٔ \f3-windowtitle\fR حذف شود، دستور \f3javadoc\fR از مقدار گزینهٔ \f3-doctitle\fR برای \f3-windowtitle\fR استفاده می‌کند\&. برای مثال، \f3javadoc -windowtitle "Java SE Platform" com\&.mypackage\fR\&. .TP -doctitle \fItitle\fR .br عنوانی را برای قرار گرفتن در نزدیکی بالای فایل خلاصهٔ نمای کلی مشخص می‌کند\&. متنی که در برچسب \f3title\fR مشخص می‌شود، به عنوان یک سرتیتر سطح‌یک و وسط‌چین مستقیماً در زیر نوار ناوبری بالایی قرار می‌گیرد\&. برچسب \f3title\fR می‌تواند شامل برچسب‌های HTML و فاصله باشد، اما در این صورت، باید عنوان را در علامت نقل‌قول محصور کنید\&. علامت‌های نقل‌قول درونی در برچسب \f3title\fR باید گریز داده شوند\&. برای مثال: \f3javadoc -header "<b>Java Platform </b><br>v1\&.4" com\&.mypackage\&.\fR .TP -title \fItitle\fR .br دیگر وجود ندارد\&. این گزینه فقط در نسخه‌های بتای Javadoc 1\&.2 وجود داشت و به \f3-doctitle\fR تغییر نام پیدا کرد\&. این تغییر نام انجام شد تا مشخص شود این گزینه عنوان سند را تعیین می‌کند، نه عنوان پنجره را\&. .TP -header \fIheader\fR .br متن سربرگ را برای قرار گرفتن در بالای هر فایل خروجی مشخص می‌کند\&. سربرگ در سمت راست نوار ناوبری بالایی قرار می‌گیرد\&. مقدار \f3header\fR می‌تواند حاوی برچسب‌های HTML و فاصله باشد، اما در این حالت باید در علامت نقل‌قول قرار گیرد\&. برای علامت‌های نقل‌قول درونی در یک سربرگ از نویسه‌های گریز استفاده کنید\&. برای مثال: \f3javadoc -header "<b>Java Platform </b><br>v1\&.4" com\&.mypackage\&.\fR .TP -footer \fIfooter\fR .br متن پاورقی را برای قرار گرفتن در پایین هر فایل خروجی مشخص می‌کند\&. مقدار \fIfooter\fR در سمت راست نوار ناوبری پایینی قرار می‌گیرد\&. مقدار \f3footer\fR می‌تواند شامل برچسب‌های HTML و فاصله باشد، اما در این صورت باید درون علامت‌های نقل‌قول قرار گیرد\&. برای هر نقل‌قول درونی در پاورقی از نویسه‌های گریز استفاده کنید\&. .TP -top .br متنی را برای قرار گرفتن در بالای هر فایل خروجی مشخص می‌کند\&. .TP -bottom \fItext\fR .br متنی را برای قرار گرفتن در پایین هر فایل خروجی مشخص می‌کند\&. این متن در پایین برگه، در زیر نوار ناوبری پایینی قرار می‌گیرد\&. متن می‌تواند شامل برچسب‌های HTML و فاصله باشد، اما در این حالت باید در علامت نقل‌قول قرار داده شود\&. برای هر علامت نقل‌قول درونی در متن از نویسه‌های گریز استفاده کنید\&. .TP -link \fIextdocURL\fR .br پیوندهایی به مستندات موجودِ تولیدشده توسط Javadoc برای کلاس‌های مرجع خارجی ایجاد می‌کند\&. آرگومان \fIextdocURL\fR نشانی URL مطلق یا نسبی دایرکتوری‌ای است که مستندات خارجی ساخته‌شده توسط Javadoc را در خود دارد\&. می‌توانید چندین گزینهٔ \f3-link\fR را در یک اجرای دستور \f3javadoc\fR برای پیوند دادن به چندین سند مشخص کنید\&. فایل package-list باید در این دایرکتوری یافت شود (در غیر این صورت، از گزینهٔ \f3-linkoffline\fR استفاده کنید)\&. دستور \f3javadoc\fR نام بسته‌ها را از فایل package-list می‌خواند و به آن بسته‌ها در آن نشانی URL پیوند ایجاد می‌کند\&. هنگامی که دستور \f3javadoc\fR اجرا می‌شود، مقدار \fIextdocURL\fR در پیوندهای \f3<A HREF>\fR ساخته‌شده رونوشت می‌شود\&. بنابراین، \fIextdocURL\fR باید نشانی دایرکتوری باشد، نه یک فایل\&. شما می‌توانید از یک پیوند مطلق برای \fIextdocURL\fR استفاده کنید تا اسناد شما امکان پیوند به سندی روی هر وب‌سایتی را داشته باشند، یا می‌توانید از پیوند نسبی برای پیوند تنها به یک موقعیت مکانی نسبی بهره بگیرید\&. در صورت استفاده از پیوند نسبی، مقداری که ارائه می‌دهید باید مسیر نسبی از دایرکتوری مقصد (مشخص‌شده با گزینهٔ \f3-d\fR) به دایرکتوری حاوی بسته‌های مورد پیوند باشد\&. هنگام تعیین پیوند مطلق، معمولاً از پیوند HTTP استفاده می‌شود\&. با این حال، اگر می‌خواهید به سیستم فایلی که فاقد وب‌سرور است پیوند دهید، می‌توانید از پیوند file استفاده کنید\&. پیوند file را تنها زمانی به کار ببرید که همهٔ افرادی که به مستندات تولیدشده دسترسی دارند، در سیستم فایل یکسانی مشترک باشند\&. در تمامی موارد و در تمامی سیستم‌های عامل، از ممیز (اسلش) به عنوان جداکننده استفاده کنید، خواه URL مطلق باشد یا نسبی، و همان‌طور که در یادداشت URL: Uniform Resource Locators در <http://www\&.ietf\&.org/rfc/rfc1738\&.txt> مشخص شده است، از \f3http:\fR یا \f3file:\fR استفاده کنید\&. .sp .nf \f3\-link http://<host>/<directory>/<directory>/\&.\&.\&./<name>\fP .fi .nf \f3\-link file://<host>/<directory>/<directory>/\&.\&.\&./<name>\fP .fi .nf \f3\-link <directory>/<directory>/\&.\&.\&./<name>\fP .fi .nf \f3\fP .fi .sp .PP تفاوت‌های بین گزینه‌های -linkoffline و -link از گزینهٔ \f3-link\fR در موارد زیر استفاده کنید: .TP 0.2i \(bu هنگامی که از مسیر نسبی به سند API خارجی استفاده می‌کنید\&. .TP 0.2i \(bu هنگامی که از نشانی URL مطلق به سند API خارجی استفاده می‌کنید در صورتی که پوستهٔ (shell) شما اجازهٔ باز کردن اتصال به آن URL را برای خواندن فراهم سازد\&..PP هنگامی که از یک URL مطلق برای سند API خارجی استفاده می‌کنید، اگر شل شما به برنامه‌ای اجازه باز کردن اتصال به آن URL برای خواندن را نمی‌دهد، از گزینه \f3-linkoffline\fR استفاده کنید\&. این حالت می‌تواند زمانی رخ دهد که پشت یک فایروال قرار دارید و سندی که می‌خواهید به آن پیوند دهید در سمت دیگر آن است\&. .PP \f3مثال ۱: پیوند مطلق به اسناد خارجی\fR .PP اگر می‌خواهید به بسته‌های \f3java\&.lang\fR، \f3java\&.io\fR و سایر بسته‌های پلتفرم Java که در http://docs\&.oracle\&.com/javase/8/docs/api/index\&.html نشان داده شده‌اند پیوند برقرار کنید، از دستور زیر استفاده کنید: .sp .nf \f3javadoc \-link http://docs\&.oracle\&.com/javase/8/docs/api com\&.mypackage\fP .fi .nf \f3\fP .fi .sp این دستور مستندات را برای بسته \f3com\&.mypackage\fR همراه با پیوندهایی به بسته‌های Java SE تولید می‌کند\&. مستندات تولیدشده به عنوان مثال در درخت کلاس‌ها (\f3trees\fR)، شامل پیوندهایی به کلاس \f3Object\fR خواهد بود\&. سایر گزینه‌ها مانند گزینه‌های \f3-sourcepath\fR و \f3-d\fR نشان داده نشده‌اند\&. .PP \f3مثال ۲: پیوند نسبی به اسناد خارجی\fR .PP در این مثال، دو بسته با مستنداتی وجود دارند که در اجراهای متفاوتی از دستور \f3javadoc\fR تولید می‌شوند و این مستندات با یک مسیر نسبی از یکدیگر جدا شده‌اند\&. این بسته‌ها عبارتند از \f3com\&.apipackage\fR (یک API) و \f3com\&.spipackage\fR (یک رابط ارائه‌دهنده خدمات یا SPI)\&. شما می‌خواهید مستندات در docs/api/com/apipackage و docs/spi/com/spipackage قرار گیرند\&. با فرض اینکه مستندات بسته API از قبل تولید شده است و docs دایرکتوری جاری است، با اجرای دستور زیر بسته SPI را با پیوندهایی به مستندات API مستندسازی می‌کنید: \f3javadoc -d \&./spi -link \&.\&./api com\&.spipackage\fR\&. .PP توجه داشته باشید که گزینه \f3-link\fR نسبت به دایرکتوری مقصد (docs/spi) نسبی است\&. .PP نکات گزینه \f3-link\fR به شما امکان می‌دهد به کلاس‌هایی پیوند دهید که در کد شما به آن‌ها ارجاع داده شده، اما در اجرای فعلی دستور \f3javadoc\fR مستندسازی نشده‌اند\&. برای اینکه این پیوندها به صفحات معتبری هدایت شوند، باید بدانید آن صفحات HTML در کجا قرار دارند و آن مکان را با \f3extdocURL\fR مشخص کنید\&. این کار به مستندات شخص ثالث اجازه می‌دهد به مستندات java\&.* در http://docs\&.oracle\&.com پیوند دهند\&. هنگامی که می‌خواهید دستور \f3javadoc\fR فقط به APIهای درون مستنداتی که در اجرای فعلی تولید می‌شوند پیوند ایجاد کند، گزینه \f3-link\fR را حذف کنید\&. بدون گزینه \f3-link\fR، دستور \f3javadoc\fR پیوندی به مستندات ارجاعات خارجی ایجاد نمی‌کند، زیرا نمی‌داند آیا چنین مستنداتی وجود دارند یا در کجا قرار دارند\&. گزینه \f3-link\fR می‌تواند در چندین بخش از مستندات تولیدشده پیوند ایجاد کند؛ بخش Process Source Files را ببینید\&. کاربرد دیگر برای پیوندهای متقابل (cross-links) بین مجموعه‌هایی از بسته‌ها است: دستور \f3javadoc\fR را روی یک مجموعه از بسته‌ها اجرا کنید، سپس دستور \f3javadoc\fR را دوباره روی مجموعه دیگری از بسته‌ها اجرا نمایید و بدین ترتیب پیوندهای دوطرفه بین هر دو مجموعه ایجاد کنید\&. .PP نحوه ارجاع به یک کلاس برای اینکه پیوند به یک کلاس ارجاع داده‌شده خارجی ظاهر شود (و نه صرفاً برچسب متنی آن)، کلاس باید به شیوه زیر ارجاع داده شود\&. ارجاع به آن در بدنه یک متد کافی نیست\&. باید در یک عبارت \f3import\fR یا در یک اعلان (declaration) به آن ارجاع داده شود\&. در اینجا مثال‌هایی از نحوه ارجاع به کلاس \f3java\&.io\&.File\fR آمده است: .PP \fI\fRدر هر نوع عبارت import: با استفاده از نویسه عمومی (wildcard import)، وارد کردن صریح با نام، یا وارد کردن خودکار برای \f3java\&.lang\&.*\fR\&. .PP در Java SE نسخه 1\&.3\&.\fIn\fR و 1\&.2\&.\fIn\fR، تنها وارد کردن صریح با نام کار می‌کند\&. عبارت \f3import\fR با نویسه عمومی کار نمی‌کند، و همچنین \f3import java\&.lang\&.*\fR خودکار نیز عمل نمی‌کند\&. .PP \fI\fRدر یک اعلان: \f3void mymethod(File f) {}\fR .PP این ارجاع می‌تواند در نوع بازگشتی یا نوع پارامتر یک متد، سازنده (constructor)، فیلد، کلاس یا رابط (interface)، یا در عبارات implements، extends یا throws باشد\&. .PP یک نتیجه مهم این است که هنگام استفاده از گزینه \f3-link\fR، ممکن است پیوندهای زیادی به دلیل این محدودیت ناخواسته ظاهر نشوند\&. متن بدون اینکه یک پیوند باشد نمایش داده خواهد شد\&. می‌توانید این موارد را از روی هشدارهایی که صادر می‌کنند شناسایی کنید\&. ساده‌ترین راه برای ارجاع مناسب به یک کلاس و افزودن پیوند، وارد کردن (import) آن کلاس است\&. .PP فهرست بسته‌ها (Package List) گزینه \f3-link\fR مستلزم آن است که فایلی با نام package-list، که توسط دستور \f3javadoc\fR تولید می‌شود، در URL تعیین‌شده با گزینه \f3-link\fR وجود داشته باشد\&. فایل package-list یک فایل متنی ساده است که نام بسته‌های مستندسازی‌شده در آن مکان را فهرست می‌کند\&. در مثال قبلی، دستور \f3javadoc\fR به دنبال فایلی به نام package-list در URL مشخص‌شده می‌گردد، نام بسته‌ها را می‌خواند و به آن بسته‌ها در آن URL پیوند می‌دهد\&. .PP برای مثال، فهرست بسته‌ها برای Java SE API در http://docs\&.oracle\&.com/javase/8/docs/api/package-list قرار دارد\&. .PP فهرست بسته‌ها به صورت زیر آغاز می‌شود: .sp .nf \f3java\&.applet\fP .fi .nf \f3java\&.awt\fP .fi .nf \f3java\&.awt\&.color\fP .fi .nf \f3java\&.awt\&.datatransfer\fP .fi .nf \f3java\&.awt\&.dnd\fP .fi .nf \f3java\&.awt\&.event\fP .fi .nf \f3java\&.awt\&.font\fP .fi .nf \f3and so on \&.\&.\&.\&.\fP .fi .nf \f3\fP .fi .sp هنگامی که \f3javadoc\fR بدون گزینه \f3-link\fR اجرا می‌شود و به نامی برمی‌خورد که متعلق به یک کلاس ارجاع داده‌شده خارجی است، نام را بدون هیچ پیوندی چاپ می‌کند\&. با این حال، هنگامی که گزینه \f3-link\fR استفاده می‌شود، دستور \f3javadoc\fR فایل package-list را در مکان مشخص‌شده توسط \fIextdocURL\fR برای یافتن نام آن بسته جستجو می‌کند\&. هنگامی که نام بسته را پیدا کرد، \fIextdocURL\fR را به عنوان پیشوند به نام اضافه می‌کند\&. .PP برای اینکه هیچ پیوند شکسته‌ای وجود نداشته باشد، تمام مستندات مربوط به ارجاعات خارجی باید در URLهای مشخص‌شده موجود باشند\&. دستور \f3javadoc\fR وجود این صفحات را بررسی نمی‌کند، بلکه تنها وجود package-list را بررسی می‌نماید\&. .PP پیوندهای چندگانه می‌توانید چندین گزینه \f3-link\fR را برای پیوند به هر تعداد سند تولیدشده خارجی ارائه دهید\&. در Javadoc 1\&.2 یک باگ شناخته‌شده وجود دارد که مانع از ارائه بیش از یک گزینه \f3-link\fR می‌شود\&. این مشکل در Javadoc 1\&.2\&.2 برطرف شد\&. برای هر سند خارجی که می‌خواهید به آن پیوند دهید یک گزینه پیوند جداگانه مشخص کنید: \f3javadoc -link extdocURL1 -link extdocURL2 \&.\&.\&. -link extdocURLn com\&.mypackage\fR که در آن \fIextdocURL1\fR، \fIextdocURL2\fR، \&.\f3\&.\&. extdocURLn\fR به ترتیب به ریشه اسناد خارجی اشاره دارند که هر کدام حاوی فایلی به نام package-list هستند\&. .PP پیوندهای متقابل (Cross Links) توجه داشته باشید هنگام پیوند متقابل بین دو یا چند سند که قبلاً تولید شده‌اند، ممکن است خودراه‌اندازی (bootstrapping) لازم باشد\&. اگر هنگام اجرای دستور \f3javadoc\fR بر روی سند اول، package-list برای هیچ‌یک از اسناد وجود نداشته باشد، در نتیجه package-list هنوز برای سند دوم نیز وجود ندارد\&. بنابراین، برای ایجاد پیوندهای خارجی، باید پس از تولید سند دوم، سند اول را مجدداً تولید کنید\&. .PP در این حالت، هدف از تولید اولیه یک سند، ایجاد فایل package-list آن است (یا در صورت اطمینان از نام بسته‌ها می‌توانید آن را دستی بسازید)\&. سپس، سند دوم را به همراه پیوندهای خارجی آن تولید کنید\&. دستور \f3javadoc\fR در صورتی که فایل خارجی package-list مورد نیاز وجود نداشته باشد، یک هشدار چاپ می‌کند\&. .TP -linkoffline \fIextdocURL packagelistLoc\fR .br این گزینه گونه‌ای از گزینه \f3-link\fR است\&. هر دوی آن‌ها پیوندهایی به مستندات تولیدشده توسط Javadoc برای کلاس‌های ارجاع داده‌شده خارجی ایجاد می‌کنند\&. هنگامی که دستور \f3javadoc\fR نمی‌تواند از طریق اتصال وب به سندی دسترسی پیدا کند، برای پیوند به آن سند در وب از گزینه \f3-linkoffline\fR استفاده کنید\&. زمانی از گزینه \f3-linkoffline\fR استفاده کنید که فایل package-list سند خارجی در مکان \f3extdocURL\fR قابل دسترسی نبوده یا وجود ندارد، اما در مکان متفاوتی که با \f3packageListLoc\fR مشخص می‌شود (معمولاً محلی) وجود دارد\&. اگر \f3extdocURL\fR فقط در وب جهانی قابل دسترسی است، گزینه \f3-linkoffline\fR این محدودیت را که دستور \f3javadoc\fR برای تولید مستندات الزاماً باید اتصال وب داشته باشد برطرف می‌کند\&. کاربرد دیگر به عنوان یک راهکار برای به‌روزرسانی اسناد است: پس از اجرای دستور \f3javadoc\fR روی یک مجموعه کامل از بسته‌ها، می‌توانید دستور \f3javadoc\fR را دوباره روی مجموعه کوچک‌تری از بسته‌های تغییریافته اجرا کنید، تا فایل‌های به‌روزرسانی‌شده بتوانند مجدداً درون مجموعه اصلی جای‌گذاری شوند\&. در ادامه مثال‌هایی ارائه شده است\&. گزینه \f3-linkoffline\fR دو آرگومان می‌گیرد: اولی رشته‌ای است که باید در پیوندهای \f3<a href>\fR تعبیه شود، و دومی به گزینه \f3-linkoffline\fR اعلام می‌کند فایل package-list را در کجا پیدا کند: .RS .TP 0.2i \(bu مقدار \f3extdocURL\fR نشانی URL مطلق یا نسبی دایرکتوری‌ای است که حاوی مستندات خارجی تولیدشده با Javadoc است که می‌خواهید به آن پیوند دهید\&. در صورت نسبی بودن، این مقدار باید مسیر نسبی از دایرکتوری مقصد (مشخص‌شده با گزینه \f3-d\fR) به ریشه بسته‌های در حال پیوند باشد\&. برای اطلاعات بیشتر، \fIextdocURL\fR را در گزینه \f3-link\fR ببینید\&. .TP 0.2i \(bu مقدار \f3packagelistLoc\fR مسیر یا URL به دایرکتوری‌ای است که شامل فایل package-list برای مستندات خارجی است\&. این مقدار می‌تواند یک URL (مانند :http یا :file) یا مسیر فایل، و به صورت مطلق یا نسبی باشد\&. در صورت نسبی بودن، آن را نسبت به دایرکتوری جاری که دستور \f3javadoc\fR از آنجا اجرا شده مشخص کنید\&. نام فایل package-list را درج نکنید\&. می‌توانید چندین گزینه \f3-linkoffline\fR را در یک اجرای معین دستور \f3javadoc\fR مشخص کنید\&. پیش از Javadoc 1\&.2\&.2، گزینه‌های \f3-linkfile\fR تنها یک‌بار قابل تعیین بودند\&. .RE .PP پیوندهای مطلق به اسناد خارجی ممکن است در شرایطی باشید که بخواهید به بسته‌های \f3java\&.lang\fR، \f3java\&.io\fR و سایر بسته‌های Java SE در http://docs\&.oracle\&.com/javase/8/docs/api/index\&.html پیوند دهید\&. .PP با این حال، شل شما به وب دسترسی ندارد\&. در این حالت، مراحل زیر را انجام دهید: .TP 0.4i 1\&. فایل package-list را در یک مرورگر در آدرس http://docs\&.oracle\&.com/javase/8/docs/api/package-list باز کنید\&. .TP 0.4i 2\&. فایل را در یک دایرکتوری محلی ذخیره کرده و با آرگومان دوم، \f3packagelistLoc\fR، به این نسخه محلی اشاره کنید\&. در این مثال، فایل فهرست بسته‌ها در دایرکتوری جاری (\&.) ذخیره شده است\&. .PP دستور زیر مستندات را برای بسته \f3com\&.mypackage\fR همراه با پیوندهایی به بسته‌های Java SE تولید می‌کند\&. مستندات تولیدشده به عنوان مثال در درخت کلاس‌ها (\f3trees\fR)، شامل پیوندهایی به کلاس \f3Object\fR خواهد بود\&. سایر گزینه‌های ضروری مانند \f3-sourcepath\fR نشان داده نشده‌اند\&. .sp .nf \f3javadoc \-linkoffline http://docs\&.oracle\&.com/javase/8/docs/api \&. com\&.mypackage \fP .fi .nf \f3\fP .fi .sp .PP پیوندهای نسبی به اسناد خارجی استفاده از \f3-linkoffline\fR با مسیرهای نسبی چندان رایج نیست، به این دلیل ساده که گزینه \f3-link\fR معمولاً کافی است\&. هنگامی که از گزینه \f3-linkoffline\fR استفاده می‌کنید، فایل package-list معمولاً محلی است، و هنگامی که از پیوندهای نسبی استفاده می‌کنید، فایلی که به آن پیوند می‌دهید نیز محلی است؛ بنابراین معمولاً نیازی به ارائه مسیر متفاوت برای دو آرگومان گزینه \f3-linkoffline\fR وجود ندارد\&. هنگامی که هر دو آرگومان یکسان باشند، می‌توانید از گزینه \f3-link\fR استفاده کنید\&. .PP ایجاد دستی فایل package-list اگر فایل package-list هنوز وجود ندارد، اما می‌دانید سند شما به چه نام بسته‌هایی پیوند خواهد خورد، می‌توانید به صورت دستی نسخه خود را از این فایل ایجاد کنید و مسیر آن را با \f3packagelistLoc\fR مشخص نمایید\&. یک مثال می‌تواند همان مورد قبلی باشد که در آن هنگام تولید اولیه \f3com\&.apipackage\fR، فهرست بسته‌ها برای \f3com\&.spipackage\fR وجود نداشت\&. این روش زمانی مفید است که نیاز به تولید مستنداتی دارید که به مستندات خارجی جدیدی پیوند دارند که نام بسته‌های آن‌ها را می‌دانید، اما هنوز منتشر نشده‌اند\&. همچنین این روشی برای ایجاد فایل‌های package-list برای بسته‌های تولیدشده با Javadoc 1\&.0 یا 1\&.1 است که در آن‌ها فایل package-list تولید نمی‌شد\&. به همین ترتیب، دو شرکت می‌توانند فایل‌های package-list منتشرنشده خود را به اشتراک بگذارند تا بتوانند مستندات با پیوند متقابل خود را به طور همزمان عرضه کنند\&. .PP پیوند به چندین سند می‌توانید به ازای هر سند تولیدشده‌ای که می‌خواهید به آن ارجاع دهید، یک‌بار گزینه \f3-linkoffline\fR را مشخص کنید: .sp .nf \f3javadoc \-linkoffline extdocURL1 packagelistLoc1 \-linkoffline extdocURL2\fP .fi .nf \f3packagelistLoc2 \&.\&.\&.\fP .fi .nf \f3\fP .fi .sp .PP به‌روزرسانی اسناد همچنین می‌توانید زمانی که پروژه‌تان ده‌ها یا صدها بسته دارد، از گزینه \f3-linkoffline\fR استفاده کنید\&. اگر پیش‌تر دستور \f3javadoc\fR را روی کل درخت کد مبدأ اجرا کرده‌اید، می‌توانید به سرعت تغییرات کوچکی در کامنت‌های مستندسازی (documentation comments) اعمال کرده و دستور \f3javadoc\fR را روی بخشی از درخت کد مبدأ دوباره اجرا کنید\&. توجه داشته باشید که اجرای دوم تنها زمانی به درستی کار می‌کند که تغییرات شما صرفاً در کامنت‌های مستندسازی باشد و نه در اعلان‌ها\&. اگر هرگونه اعلانی را به کد مبدأ اضافه یا حذف کنید یا تغییر دهید، ممکن است پیوندهای شکسته در نمایه (index)، درخت بسته (package tree)، فهرست‌های اعضای موروثی، صفحه Use و جاهای دیگر ظاهر شوند\&. .PP ابتدا یک دایرکتوری مقصد جدید، مانند update، برای این اجرای کوچک جدید ایجاد کنید\&. در این مثال، نام دایرکتوری مقصد اصلی html است\&. در ساده‌ترین مثال، به دایرکتوری والد html بروید\&. آرگومان اول گزینه \f3-linkoffline\fR را روی دایرکتوری جاری (\&.) تنظیم کرده و آرگومان دوم را روی مسیر نسبی به html، جایی که می‌تواند package-list را بیابد، تنظیم نمایید و تنها نام بسته‌هایی را که می‌خواهید به‌روزرسانی شوند وارد کنید: .sp .nf \f3javadoc \-d update \-linkoffline \&. html com\&.mypackage\fP .fi .nf \f3\fP .fi .sp پس از اتمام دستور \f3javadoc\fR، این صفحات کلاس تولیدشده در update/com/package را (نه نمای کلی overview یا نمایه index) روی فایل‌های اصلی در html/com/package کپی کنید\&. .TP -linksource .br یک نسخه HTML از هر فایل مبدأ (همراه با شماره خطوط) ایجاد کرده و پیوندهایی از مستندات HTML استاندارد به آن‌ها اضافه می‌کند\&. پیوندها برای کلاس‌ها، رابط‌ها، سازنده‌ها، متدها و فیلدهایی که اعلان آن‌ها در یک فایل مبدأ است ایجاد می‌شوند\&. در غیر این صورت، پیوندی ایجاد نمی‌شود؛ مانند سازنده‌های پیش‌فرض و کلاس‌های تولیدشده\&. این گزینه تمام جزئیات پیاده‌سازی خصوصی را در فایل‌های مبدأ مشخص‌شده آشکار می‌کند، از جمله کلاس‌های خصوصی، فیلدهای خصوصی و بدنه متدهای خصوصی، صرف‌نظر از گزینه‌های \f3-public\fR، \f3-package\fR، \f3-protected\fR و \f3-private\fR\&. مگر اینکه از گزینه \f3-private\fR نیز استفاده کنید، همه کلاس‌ها یا رابط‌های خصوصی از طریق پیوندها قابل دسترسی نخواهند بود\&. هر پیوند روی نام شناسه در اعلان آن ظاهر می‌شود\&. به عنوان مثال، پیوند به کد مبدأ کلاس \f3Button\fR روی کلمه \f3Button\fR خواهد بود: .sp .nf \f3public class Button extends Component implements Accessible\fP .fi .nf \f3\fP .fi .sp پیوند به کد مبدأ متد \f3getLabel\fR در کلاس \f3Button\fR روی کلمه \f3getLabel\fR قرار دارد: .sp .nf \f3public String getLabel()\fP .fi .nf \f3\fP .fi .sp .TP -group groupheading \fIpackagepattern:packagepattern\fR .br بسته‌ها را در صفحه مرور کلی (overview) بر اساس گروه‌هایی که مشخص می‌کنید دسته‌بندی می‌کند، یک گروه در هر جدول\&. شما هر گروه را با یک گزینه \f3-group\fR مجزا مشخص می‌کنید\&. گروه‌ها به ترتیبی که در خط فرمان مشخص شده‌اند در صفحه ظاهر می‌شوند\&. بسته‌ها در داخل یک گروه به ترتیب الفبا مرتب می‌شوند\&. برای یک گزینه \f3-group\fR معین، بسته‌های منطبق با فهرست عبارات \f3packagepattern\fR در جدولی با عنوان \fIgroupheading\fR نمایش داده می‌شوند\&. .RS .TP 0.2i \(bu مقدار \f3groupheading\fR می‌تواند هر متنی باشد و شامل فاصله (white space) نیز بشود\&. این متن در سربرگ جدول برای آن گروه قرار داده می‌شود\&..TP 0.2i \(bu مقدار \f3packagepattern\fR می‌تواند هر نام بسته‌ای در ابتدای نام هر بسته‌ای باشد که به دنبال آن یک ستاره (*) آمده است\&. ستاره تنها نویسهٔ عام (wildcard) مجاز است و به معنای تطبیق با هر نویسه‌ای می‌باشد\&. با جدا کردن الگوها به‌وسیلهٔ دونقطه (:) می‌توان چند الگو را در یک گروه قرار داد\&. اگر در یک الگو یا فهرستی از الگوها از ستاره استفاده می‌کنید، فهرست الگوها باید داخل علامت نقل‌قول قرار گیرد، مانند \f3"java\&.lang*:java\&.util"\fR\&. .RE هنگامی که گزینهٔ \f3-group\fR را مشخص نکنید، همهٔ بسته‌ها در یک گروه با عنوان \fIPackages\fR و زیرعنوان‌های مناسب قرار می‌گیرند\&. اگر زیرعنوان‌ها شامل همهٔ بسته‌های مستندسازی‌شده نباشند (همهٔ گروه‌ها)، بسته‌های باقی‌مانده در گروهی جداگانه با زیرعنوان Other Packages ظاهر می‌شوند\&. به عنوان مثال، دستور \f3javadoc\fR زیر بسته‌های مستندسازی‌شده را به سه دستهٔ \fICore\fR، \fIExtension\fR و \fIOther Packages\fR تفکیک می‌کند\&. نقطهٔ انتهایی (\&.) در \f3java\&.lang*\fR ظاهر نمی‌شود\&. گنجاندن نقطه، مانند \f3java\&.lang\&.*\fR، بستهٔ \f3java\&.lang\fR را حذف می‌کند\&. .sp .nf \f3javadoc \-group "Core Packages" "java\&.lang*:java\&.util"\fP .fi .nf \f3 \-group "Extension Packages" "javax\&.*"\fP .fi .nf \f3 java\&.lang java\&.lang\&.reflect java\&.util javax\&.servlet java\&.new\fP .fi .nf \f3\fP .fi .sp \fICore Packages\fR \f3java\&.lang\fR \f3java\&.lang\&.reflect\fR \f3java\&.util\fR \fIExtension Packages\fR \f3javax\&.servlet\fR \fIOther Packages\fR \f3java\&.new\fR .TP -nodeprecated .br از تولید هرگونه API منسوخ‌شده (deprecated) در مستندات جلوگیری می‌کند\&. این گزینه کاری را انجام می‌دهد که گزینهٔ \f3-nodeprecatedlist\fR انجام می‌دهد، بعلاوه در بقیهٔ بخش‌های مستندات نیز هیچ API منسوخ‌شده‌ای تولید نمی‌کند\&. این ویژگی هنگام نوشتن کد، زمانی که نمی‌خواهید تمرکزتان توسط کدهای منسوخ‌شده برهم بخورد، مفید است\&. .TP -nodeprecatedlist .br از تولید فایلی که شامل فهرست APIهای منسوخ‌شده است (deprecated-list\&.html) و پیوند موجود در نوار ناوبری به آن صفحه جلوگیری می‌کند\&. دستور \f3javadoc\fR همچنان به تولید APIهای منسوخ‌شده در سرتاسر سایر بخش‌های سند ادامه می‌دهد\&. این ویژگی زمانی مفید است که کد مبدأ شما فاقد هرگونه API منسوخ‌شده باشد و بخواهید نوار ناوبری خلوت‌تری داشته باشید\&. .TP -nosince .br بخش‌های \f3Since\fR مربوط به برچسب‌های \f3@since\fR را از اسناد تولیدشده حذف می‌کند\&. .TP -notree .br صفحات سلسله‌مراتب کلاس/رابط را از اسناد تولیدشده حذف می‌کند\&. این‌ها صفحاتی هستند که با استفاده از دکمهٔ Tree در نوار ناوبری به آن‌ها دسترسی پیدا می‌کنید\&. این سلسله‌مراتب به‌طور پیش‌فرض تولید می‌شود\&. .TP -noindex .br نمایه (index) را از اسناد تولیدشده حذف می‌کند\&. نمایه به‌طور پیش‌فرض تولید می‌شود\&. .TP -nohelp .br پیوند HELP را از نوارهای ناوبری در بالا و پایین هر صفحه از خروجی حذف می‌کند\&. .TP -nonavbar .br از تولید نوار ناوبری، سربرگ و پابرگ که معمولاً در بالا و پایین صفحات تولیدشده وجود دارند، جلوگیری می‌کند\&. گزینهٔ \f3-nonavbar\fR هیچ تأثیری بر گزینهٔ \f3-bottom\fR ندارد\&. گزینهٔ \f3-nonavbar\fR زمانی مفید است که فقط به محتوا علاقه دارید و نیازی به ناوبری ندارید، مانند زمانی که فایل‌ها را صرفاً برای چاپ به PostScript یا PDF تبدیل می‌کنید\&. .TP -helpfile \fIpath\efilename\fR .br مسیر یک فایل راهنمای جایگزین \fIpath\efilename\fR را مشخص می‌کند که پیوند HELP در نوارهای ناوبری بالا و پایین به آن ارجاع می‌دهد\&. بدون این گزینه، دستور \f3javadoc\fR یک فایل راهنمای help-doc\&.html ایجاد می‌کند که مسیر آن در خودِ دستور \f3javadoc\fR کدگذاری ثابت شده است\&. این گزینه به شما امکان می‌دهد رفتار پیش‌فرض را بازنویسی کنید\&. نام فایل می‌تواند هر نامی باشد و محدود به help-doc\&.html نیست\&. دستور \f3javadoc\fR پیوندهای نوار ناوبری را بر همان اساس تنظیم می‌کند، برای مثال: .sp .nf \f3javadoc \-helpfile /home/user/myhelp\&.html java\&.awt\&.\fP .fi .nf \f3\fP .fi .sp .TP -stylesheet \fIpath/filename\fR .br مسیر یک فایل شیوه‌نامهٔ (stylesheet) جایگزین HTML را مشخص می‌کند\&. بدون این گزینه، دستور \f3javadoc\fR به‌طور خودکار یک فایل شیوه‌نامه به نام stylesheet\&.css ایجاد می‌کند که درون دستور \f3javadoc\fR به صورت کدگذاری ثابت تعبیه شده است\&. این گزینه امکان بازنویسی مقدار پیش‌فرض را فراهم می‌کند\&. نام فایل می‌تواند هر نامی باشد و محدود به stylesheet\&.css نیست، برای مثال: .sp .nf \f3javadoc \-stylesheet file /home/user/mystylesheet\&.css com\&.mypackage\fP .fi .nf \f3\fP .fi .sp .TP -serialwarn .br هشدارهای زمان ترجمه (کامپایل) را برای برچسب‌های گم‌شدهٔ \f3@serial\fR تولید می‌کند\&. به‌طور پیش‌فرض، Javadoc 1\&.2\&.2 و نسخه‌های پس از آن هیچ هشدار سریالی‌سازی تولید نمی‌کنند\&. این رفتار در مقایسه با نسخه‌های پیشین معکوس شده است\&. از این گزینه برای نمایش هشدارهای سریالی‌سازی استفاده کنید، که به مستندسازی مناسب فیلدهای سریالی‌پذیر پیش‌فرض و متدهای \f3writeExternal\fR کمک می‌کند\&. .TP -charset \fIname\fR .br مجموعه‌نویسهٔ (character set) زبان HTML را برای این سند مشخص می‌کند\&. نام باید یک نام ترجیحی MIME باشد، همان‌طور که در ثبت‌نامهٔ IANA، مجموعه‌نویسه‌ها در http://www\&.iana\&.org/assignments/character-sets مشخص شده است\&. برای مثال، \f3javadoc -charset "iso-8859-1" mypackage\fR خط زیر را در بخش head هر صفحهٔ تولیدشده درج می‌کند: .sp .nf \f3<META http\-equiv="Content\-Type" content="text/html; charset=ISO\-8859\-1">\fP .fi .nf \f3\fP .fi .sp این برچسب \f3META\fR در استاندارد HTML (۴۱۹۷۲۶۵ و ۴۱۳۷۳۲۱)، HTML Document Representation، در آدرس http://www\&.w3\&.org/TR/REC-html40/charset\&.html#h-5\&.2\&.2 شرح داده شده است\&. همچنین گزینه‌های \f3-encoding\fR و \f3-docencoding name\fR را ببینید\&. .TP -docencoding \fIname\fR .br کدگذاری (encoding) فایل‌های HTML تولیدشده را مشخص می‌کند\&. نام باید یک نام ترجیحی MIME باشد، همان‌طور که در ثبت‌نامهٔ IANA، مجموعه‌نویسه‌ها در http://www\&.iana\&.org/assignments/character-sets مشخص شده است\&. اگر گزینهٔ \f3-docencoding\fR را نادیده بگیرید اما از گزینهٔ \f3-encoding\fR استفاده کنید، کدگذاری فایل‌های HTML تولیدشده توسط گزینهٔ \f3-encoding\fR تعیین می‌شود، برای مثال: \f3javadoc -docencoding "iso-8859-1" mypackage\fR\&. همچنین گزینه‌های \f3-encoding\fR و \f3-docencoding name\fR را ببینید\&. .TP -keywords .br برچسب‌های کلیدواژهٔ <META> در HTML را به فایل تولیدشده برای هر کلاس اضافه می‌کند\&. این برچسب‌ها می‌توانند به موتورهای جستجویی که به دنبال برچسب‌های <META> می‌گردند در یافتن صفحات کمک کنند\&. بیشتر موتورهای جستجویی که کل اینترنت را جستجو می‌کنند، به برچسب‌های <META> توجهی نمی‌کنند، زیرا صفحات ممکن است از آن‌ها سوءاستفاده کنند\&. موتورهای جستجوی ارائه‌شده توسط شرکت‌هایی که جستجوی خود را به وب‌سایت خودشان محدود می‌کنند، می‌توانند با بررسی برچسب‌های <META> بهره‌مند شوند\&. برچسب‌های <META> شامل نام کامل واجد شرایط (fully qualified) کلاس و نام‌های غیرواجد شرایط فیلدها و متدها هستند\&. سازنده‌ها (constructors) گنجانده نمی‌شوند زیرا با نام کلاس یکسان هستند\&. برای مثال، کلاس \f3String\fR با این کلیدواژه‌ها آغاز می‌شود: .sp .nf \f3<META NAME="keywords" CONTENT="java\&.lang\&.String class">\fP .fi .nf \f3<META NAME="keywords" CONTENT="CASE_INSENSITIVE_ORDER">\fP .fi .nf \f3<META NAME="keywords" CONTENT="length()">\fP .fi .nf \f3<META NAME="keywords" CONTENT="charAt()">\fP .fi .nf \f3\fP .fi .sp .TP -tag \fItagname\fR:Xaoptcmf:"\fItaghead\fR" .br دستور \f3javadoc\fR را قادر می‌سازد تا یک برچسب بلوکی سفارشی ساده و تک‌آرگومانی \f3@tagname\fR را در یادداشت‌های مستندسازی تفسیر کند\&. برای اینکه دستور \f3javadoc\fR بتواند املای نام برچسب‌ها را بررسی کند، مهم است که برای هر برچسب سفارشی موجود در کد مبدأ یک گزینهٔ \f3-tag\fR درج کنید و آن‌هایی را که در اجرای فعلی خروجی داده نمی‌شوند غیرفعال کنید (با \f3X\fR)\&. دونقطه (:) همواره به عنوان جداکننده عمل می‌کند\&. گزینهٔ \f3-tag\fR سربرگ برچسب \fItaghead\fR را به صورت برجسته (bold) خروجی می‌دهد که در خط بعدی متنِ تک‌آرگومان آن قرار می‌گیرد\&. مانند هر برچسب بلوکی دیگر، متن آرگومان می‌تواند حاوی برچسب‌های درون‌خطی باشد که آن‌ها نیز تفسیر می‌شوند\&. خروجی شبیه به برچسب‌های استاندارد تک‌آرگومانی، مانند برچسب‌های \f3@return\fR و \f3@author\fR است\&. حذف مقداری برای \fItaghead\fR باعث می‌شود \f3tagname\fR به عنوان سربرگ قرار گیرد\&. \fIجای‌گذاری برچسب‌ها\fR: آرگومان‌های \f3Xaoptcmf\fR مشخص می‌کنند که برچسب در کجای کد مبدأ مجاز به قرارگیری است و آیا می‌توان برچسب را غیرفعال کرد (با استفاده از \f3X\fR) یا خیر\&. می‌توانید \f3a\fR را برای مجاز کردن برچسب در همهٔ مکان‌ها، یا هر ترکیبی از حروف دیگر را مشخص کنید: \f3X\fR (غیرفعال کردن برچسب) \f3a\fR (همه) \f3o\fR (نمای کلی) \f3p\fR (بسته‌ها) \f3t\fR (نوع‌ها، یعنی کلاس‌ها و رابط‌ها) \f3c\fR (سازنده‌ها) \f3m\fR (متدها) \f3f\fR (فیلدها) \fIنمونه‌هایی از برچسب‌های منفرد\fR: نمونه‌ای از یک گزینهٔ برچسب برای برچسبی که می‌تواند در هر کجای کد مبدأ استفاده شود عبارت است از: \f3-tag todo:a:"To Do:"\fR\&. اگر می‌خواهید برچسب \f3@todo\fR فقط با سازنده‌ها، متدها و فیلدها استفاده شود، از این عبارت استفاده می‌کنید: \f3-tag todo:cmf:"To Do:"\fR\&. توجه داشته باشید که آخرین دونقطه (:) یک جداکنندهٔ پارامتر نیست، بلکه بخشی از متن سربرگ است\&. شما می‌توانید از هر یک از این گزینه‌های برچسب برای کدهای مبدئی که حاوی برچسب \f3@todo\fR هستند استفاده کنید، مانند: \f3@todo The documentation for this method needs work\fR\&. \fIعلامت دونقطه در نام برچسب‌ها\fR: برای گریز از دونقطه‌ای (escape) که می‌خواهید در نام یک برچسب استفاده کنید، از یک بک‌اسلش استفاده نمایید\&. از گزینهٔ \f3-tag ejb\e\e:bean:a:"EJB Bean:"\fR برای یادداشت مستندسازی زیر استفاده کنید: .sp .nf \f3/**\fP .fi .nf \f3 * @ejb:bean\fP .fi .nf \f3 */\fP .fi .nf \f3\fP .fi .sp \fIبررسی املای نام برچسب‌ها\fR: برخی از توسعه‌دهندگان برچسب‌های سفارشی را در کد مبدأ قرار می‌دهند که همیشه مایل به چاپ آن‌ها در خروجی نیستند\&. در این موارد، مهم است که تمام برچسب‌های موجود در کد مبدأ را فهرست کنید، برچسب‌هایی را که می‌خواهید در خروجی ظاهر شوند فعال کرده و آن‌هایی را که نمی‌خواهید غیرفعال نمایید\&. وجود \f3X\fR برچسب را غیرفعال می‌کند، در حالی که عدم وجود آن برچسب را فعال می‌سازد\&. این کار اطلاعات کافی را در اختیار دستور \f3javadoc\fR قرار می‌دهد تا بداند آیا برچسبی که با آن مواجه شده ناشناخته است (که احتمالاً نتیجهٔ یک خطای تایپی یا املای نادرست است) یا خیر\&. دستور \f3javadoc\fR در این موارد یک هشدار چاپ می‌کند\&. می‌توانید \f3X\fR را به مقادیر جای‌گذاری که از قبل موجودند اضافه کنید، به طوری که هر زمان خواستید برچسب را فعال کنید، به سادگی \f3X\fR را حذف نمایید\&. برای مثال، اگر برچسب \f3@todo\fR برچسبی است که می‌خواهید از خروجی حذف شود، می‌توانید از این عبارت استفاده کنید: \f3-tag todo:Xcmf:"To Do:"\fR\&. اگر ترجیح می‌دهید آن را ساده نگه دارید، از این دستور استفاده کنید: \f3-tag todo:X\fR\&. نحو \f3-tag todo:X\fR حتی زمانی که برچسب \f3@todo\fR توسط یک taglet تعریف شده باشد نیز کار می‌کند\&. \fIترتیب برچسب‌ها\fR: ترتیب گزینه‌های \f3-ta\fR\f3g\fR و \f3-taglet\fR ترتیب خروجی برچسب‌ها را تعیین می‌کند\&. می‌توانید برچسب‌های سفارشی را با برچسب‌های استاندارد ترکیب کنید تا در میان آن‌ها پراکنده شوند\&. گزینه‌های برچسب برای برچسب‌های استاندارد صرفاً جای‌نگه‌دار (placeholder) برای تعیین ترتیب هستند\&. آن‌ها فقط نام برچسب استاندارد را می‌پذیرند\&. زیرعنوان‌های برچسب‌های استاندارد قابل تغییر نیستند\&. این موضوع در مثال زیر نشان داده شده است\&. اگر گزینهٔ \f3-tag\fR موجود نباشد، موقعیت گزینهٔ \f3-tagle\fR\f3t\fR ترتیب آن را مشخص می‌کند\&. اگر هر دو حضور داشته باشند، هر کدام که در خط فرمان در جایگاه آخر قرار گیرد ترتیب را مشخص می‌کند\&. این به این دلیل است که برچسب‌ها و tagletها به ترتیبی که در خط فرمان ظاهر می‌شوند پردازش می‌گردند\&. برای مثال، اگر گزینه‌های \f3-taglet\fR و \f3-tag\fR دارای مقدار نام \f3todo\fR باشند، آن گزینه‌ای که در آخر خط فرمان قرار دارد ترتیب را مشخص می‌کند\&. \fIنمونه‌ای از یک مجموعهٔ کامل برچسب‌ها\fR: این مثال عبارت To Do را بعد از Parameters و قبل از Throws در خروجی درج می‌کند\&. با استفاده از \f3X\fR، همچنین مشخص می‌کند که ممکن است با برچسب \f3@example\fR در کد مبدأ مواجه شود که نباید در این اجرا خروجی داده شود\&. اگر از برچسب \f3@argfile\fR استفاده کنید، می‌توانید برچسب‌ها را در خطوط جداگانه در یک فایل آرگومان مشابه این قرار دهید (نیازی به نویسه‌های ادامه‌دهندهٔ خط نیست): .sp .nf \f3\-tag param\fP .fi .nf \f3\-tag return\fP .fi .nf \f3\-tag todo:a:"To Do:"\fP .fi .nf \f3\-tag throws\fP .fi .nf \f3\-tag see\fP .fi .nf \f3\-tag example:X\fP .fi .nf \f3\fP .fi .sp هنگامی که دستور \f3javadoc\fR یادداشت‌های مستندسازی را تجزیه می‌کند، هر برچسبی که با آن مواجه شود و نه برچسب استاندارد باشد و نه از طریق گزینه‌های \f3-tag\fR یا \f3-taglet\fR ارسال شده باشد، ناشناخته تلقی شده و یک هشدار صادر می‌شود\&. برچسب‌های استاندارد ابتدا در یک فهرست داخلی با ترتیب پیش‌فرض خود ذخیره می‌شوند\&. هر زمان که گزینه‌های \f3-tag\fR استفاده شوند، آن برچسب‌ها به انتهای این فهرست اضافه می‌شوند\&. برچسب‌های استاندارد از موقعیت پیش‌فرض خود جابه‌جا می‌شوند\&. بنابراین، اگر گزینهٔ \f3-tag\fR برای یک برچسب استاندارد نادیده گرفته شود، آن برچسب در موقعیت پیش‌فرض خود باقی می‌ماند\&. \fIجلوگیری از تداخل\fR: اگر می‌خواهید فضای نام (namespace) اختصاصی خود را بسازید، می‌توانید از شیوهٔ نام‌گذاریِ تفکیک‌شده با نقطه، مشابه آنچه برای بسته‌ها به کار می‌رود، استفاده کنید: \f3com\&.mycompany\&.todo\fR\&. شرکت Oracle به ایجاد برچسب‌های استانداردی که نام آن‌ها حاوی نقطه نیست ادامه خواهد داد\&. هر برچسبی که ایجاد کنید رفتار برچسبی با همان نام را که توسط Oracle تعریف شده است لغو (override) می‌کند\&. اگر یک برچسب یا taglet به نام \f3@todo\fR بسازید، حتی در صورتی که بعداً Oracle برچسب استانداردی با همین نام بسازد، همواره همان رفتاری را خواهد داشت که شما تعریف کرده‌اید\&. \fIحاشیه‌نویسی‌ها در برابر برچسب‌های Javadoc\fR: به‌طور کلی، اگر نشانه‌گذاری مورد نظری که می‌خواهید اضافه کنید قرار است بر مستندات تأثیر بگذارد یا آن را تولید کند، باید یک برچسب 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 مراجعه کنید\&. همچنین می‌توانید با گزینهٔ \f3-taglet\fR برچسب‌های بلوکی پیچیده‌تر یا برچسب‌های درون‌خطی سفارشی ایجاد کنید\&..TP -taglet \fIclass\fR .br فایل کلاسی را مشخص می‌کند که تگ‌لت (taglet) مورد استفاده در تولید مستندات برای آن تگ را آغاز می‌نماید\&. برای مقدار \f3class\fR از نام کامل و واجد شرایط (fully qualified name) استفاده کنید\&. این تگ‌لت همچنین تعداد آرگومان‌های متنی را که تگ سفارشی دارد مشخص می‌کند\&. تگ‌لت این آرگومان‌ها را می‌پذیرد، آن‌ها را پردازش می‌کند و خروجی را تولید می‌نماید\&. برای مستندات جامع به همراه نمونه‌های تگ‌لت، به بخش Taglet Overview در نشانی http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/taglet/overview\&.html مراجعه کنید\&. تگ‌لت‌ها برای تگ‌های بلوکی یا درون‌خطی (inline) مفید هستند\&. آن‌ها می‌توانند هر تعداد آرگومان داشته باشند و رفتارهای سفارشی را پیاده‌سازی کنند، مانند پررنگ (bold) کردن متن، قالب‌بندی بالت‌ها، نوشتن متن در یک فایل، یا آغاز فرایندهای دیگر\&. تگ‌لت‌ها تنها می‌توانند تعیین کنند که یک تگ کجا و با چه قالبی ظاهر شود\&. تمام تصمیمات دیگر توسط doclet گرفته می‌شود\&. یک تگ‌لت نمی‌تواند کارهایی مانند حذف یک نام کلاس از فهرست کلاس‌های گنجانده‌شده را انجام دهد\&. با این حال، می‌تواند اثرات جانبی (side effects) را اجرا کند، مانند چاپ متن تگ در یک فایل یا راه‌اندازی فرایندی دیگر\&. از گزینهٔ \f3-tagletpath\fR برای مشخص کردن مسیر تگ‌لت استفاده کنید\&. مثال زیر تگ‌لت To Do را بعد از Parameters و قبل از Throws در صفحات تولیدشده درج می‌کند\&. به عنوان روش جایگزین، می‌توانید از گزینهٔ \f3-taglet\fR به جای گزینهٔ \f3-tag\fR آن استفاده کنید، اما خواندن آن ممکن است دشوار باشد\&. .sp .nf \f3\-taglet com\&.sun\&.tools\&.doclets\&.ToDoTaglet\fP .fi .nf \f3\-tagletpath /home/taglets \fP .fi .nf \f3\-tag return\fP .fi .nf \f3\-tag param\fP .fi .nf \f3\-tag todo\fP .fi .nf \f3\-tag throws\fP .fi .nf \f3\-tag see\fP .fi .nf \f3\fP .fi .sp .TP -tagletpath \fItagletpathlist\fR .br مسیرهای جستجو را برای یافتن فایل‌های کلاس تگ‌لت مشخص می‌کند\&. مقدار \f3tagletpathlist\fR می‌تواند شامل چند مسیر باشد که با دونقطه (:) از یکدیگر جدا شده‌اند\&. دستور \f3javadoc\fR تمام زیردایرکتوری‌های مسیرهای مشخص‌شده را جستجو می‌کند\&. .TP -docfilesubdirs .br رونوشت‌برداری عمیق (deep copying) از دایرکتوری‌های doc-files را فعال می‌کند\&. زیردایرکتوری‌ها و تمامی محتویات به‌صورت بازگشتی در مقصد کپی می‌شوند\&. برای مثال، دایرکتوری doc-files/example/images و تمام محتویات آن کپی خواهند شد\&. همچنین گزینه‌ای برای استثنا کردن زیردایرکتوری‌ها وجود دارد\&. .TP -excludedocfilessubdir \fIname1:name2\fR .br هر یک از زیردایرکتوری‌های doc-files با نام‌های مشخص‌شده را استثنا می‌کند\&. این کار از کپی شدن زیردایرکتوری‌های SCCS و سایر دایرکتوری‌های سیستم کنترل کد منبع جلوگیری می‌کند\&. .TP -noqualifier all | \fIpackagename1\fR:\fIpackagename2\&.\&.\&.\fR .br نام‌های توصیف‌کنندهٔ بسته (qualifying package names) را از نام کلاس‌ها در خروجی حذف می‌کند\&. آرگومان گزینهٔ \f3-noqualifier\fR یا \f3all\fR است (همهٔ توصیف‌کننده‌های بسته حذف می‌شوند) یا فهرستی از بسته‌ها که با دونقطه از هم جدا شده‌اند، به همراه کاراکترهای عمومی (wildcards)، که باید به عنوان توصیف‌کننده حذف شوند\&. نام بسته از جاهایی که نام کلاس یا واسط ظاهر می‌شود حذف می‌گردد\&. بخش Process Source Files را ببینید\&. مثال زیر تمام توصیف‌کننده‌های بسته را حذف می‌کند: \f3-noqualifier all\fR\&. مثال زیر توصیف‌کننده‌های بستهٔ \f3java\&.lang\fR و \f3java\&.io\fR را حذف می‌کند: \f3-noqualifier java\&.lang:java\&.io\fR\&. مثال زیر توصیف‌کننده‌های بسته‌ای را که با \f3java\fR شروع می‌شوند و زیربسته‌های \f3com\&.sun\fR را حذف می‌کند، اما \f3javax\fR را حذف نمی‌کند: \f3-noqualifier java\&.*:com\&.sun\&.*\fR\&. در جاهایی که یک توصیف‌کنندهٔ بسته طبق رفتار پیشین ظاهر می‌شد، نام می‌تواند به شکل مناسب کوتاه شود\&. بخش How a Name Appears را ببینید\&. این قاعده چه از گزینهٔ \f3-noqualifier\fR استفاده شود و چه نشود اعمال می‌گردد\&. .TP -notimestamp .br برچسب زمانی (time stamp) را که در یک کامنت HTML در بالای هر صفحه از HTMLهای تولیدشده پنهان است، غیرفعال می‌کند\&. گزینهٔ \f3-notimestamp\fR زمانی مفید است که می‌خواهید دستور \f3javadoc\fR را روی دو پایگاه کد منبع اجرا کرده و تفاوت‌های بین آن‌ها را با \f3diff\fR به دست آورید، زیرا از این که برچسب‌های زمانی باعث ایجاد تفاوت در خروجی \f3diff\fR شوند جلوگیری می‌کند (که در غیر این صورت در هر صفحه یک \f3diff\fR ایجاد می‌شد)\&. برچسب زمانی شامل شماره انتشار دستور \f3javadoc\fR است و در حال حاضر چیزی شبیه به این ظاهر می‌شود: \f3<!-- Generated by javadoc (build 1\&.5\&.0_01) on Thu Apr 02 14:04:52 IST 2009 -->\fR\&. .TP -nocomment .br کل متن کامنت، شامل توضیحات اصلی و تمام تگ‌ها را نادیده گرفته و تنها اعلان‌ها (declarations) را تولید می‌کند\&. این گزینه به شما اجازه می‌دهد تا از فایل‌های منبعی که در ابتدا برای هدف دیگری در نظر گرفته شده بودند مجدداً استفاده کنید تا بتوانید در مراحل اولیه یک پروژه جدید، اسکلت مستندات HTML را تولید نمایید\&. .TP -sourcetab \fItablength\fR .br تعداد فاصله‌هایی (spaces) را که هر تب در سورس استفاده می‌کند مشخص می‌نماید\&. .SH "فایل‌های آرگومان خط فرمان (COMMAND-LINE ARGUMENT FILES)" برای کوتاه‌تر یا ساده‌تر کردن دستور \f3javadoc\fR، می‌توانید یک یا چند فایل حاوی آرگومان‌های دستور \f3javadoc\fR (به جز گزینه‌های \f3-J\fR) را مشخص کنید\&. این امکان به شما اجازه می‌دهد تا دستورهای \f3javadoc\fR با هر طولی را در هر سیستم‌عاملی ایجاد کنید\&. .PP یک فایل آرگومان می‌تواند شامل گزینه‌های \f3javac\fR و نام‌های فایل منبع در هر ترکیبی باشد\&. آرگومان‌های درون یک فایل می‌توانند با فاصله یا با خط جدید از یکدیگر جدا شوند\&. اگر نام فایلی دارای فاصله است، کل نام فایل را داخل علامت نقل‌قول دوتایی قرار دهید\&. .PP نام‌های فایل درون یک فایل آرگومان نسبت به دایرکتوری جاری سنجیده می‌شوند، نه نسبت به مکان فایل آرگومان\&. کاراکترهای عمومی (\f3*\fR) در این فهرست‌ها مجاز نیستند (مانند تعیین *\&.java)\&. استفاده از علامت @ برای تفسیر بازگشتی فایل‌ها پشتیبانی نمی‌شود\&. گزینه‌های \f3-J\fR پشتیبانی نمی‌شوند زیرا به اجراکننده (launcher) ارسال می‌شوند که از فایل‌های آرگومان پشتیبانی نمی‌کند\&. .PP هنگام اجرای دستور \f3javadoc\fR، مسیر و نام هر فایل آرگومان را با نویسهٔ پیشین @ ارسال کنید\&. زمانی که دستور \f3javadoc\fR با آرگومانی مواجه می‌شود که با علامت @ آغاز شده است، محتویات آن فایل را در فهرست آرگومان‌ها بسط می‌دهد\&. .PP \f3مثال ۱: تک‌فایل آرگومان\fR .PP می‌توانید از یک فایل آرگومان تکی به نام \f3argfile\fR برای نگه‌داری تمام آرگومان‌های دستور \f3javadoc\fR استفاده کنید: \f3javadoc @argfile\fR\&. فایل آرگومان \f3\fRشامل محتویات هر دو فایل است، همان‌طور که در مثال بعدی نشان داده شده است\&. .PP \f3مثال ۲: دو فایل آرگومان\fR .PP می‌توانید دو فایل آرگومان ایجاد کنید: یکی برای گزینه‌های دستور \f3javadoc\fR و دیگری برای نام‌های بسته‌ها یا نام‌های فایل‌های منبع\&. توجه داشته باشید که فهرست‌های زیر فاقد نویسه‌های ادامه‌دهندهٔ خط هستند\&. .PP فایلی به نام options ایجاد کنید که شامل موارد زیر باشد: .sp .nf \f3\-d docs\-filelist \fP .fi .nf \f3\-use \fP .fi .nf \f3\-splitindex\fP .fi .nf \f3\-windowtitle \&'Java SE 7 API Specification\&'\fP .fi .nf \f3\-doctitle \&'Java SE 7 API Specification\&'\fP .fi .nf \f3\-header \&'<b>Java\(tm SE 7</b>\&'\fP .fi .nf \f3\-bottom \&'Copyright © 1993\-2011 Oracle and/or its affiliates\&. All rights reserved\&.\&'\fP .fi .nf \f3\-group "Core Packages" "java\&.*"\fP .fi .nf \f3\-overview /java/pubs/ws/1\&.7\&.0/src/share/classes/overview\-core\&.html\fP .fi .nf \f3\-sourcepath /java/pubs/ws/1\&.7\&.0/src/share/classes\fP .fi .nf \f3\fP .fi .sp فایلی به نام packages ایجاد کنید که شامل موارد زیر باشد: .sp .nf \f3com\&.mypackage1\fP .fi .nf \f3com\&.mypackage2\fP .fi .nf \f3com\&.mypackage3\fP .fi .nf \f3\fP .fi .sp دستور \f3javadoc\fR را به صورت زیر اجرا کنید: .sp .nf \f3javadoc @options @packages\fP .fi .nf \f3\fP .fi .sp \f3مثال ۳: فایل‌های آرگومان دارای مسیر\fR .PP فایل‌های آرگومان می‌توانند مسیر داشته باشند، اما هر نام فایلی درون این فایل‌ها نسبت به دایرکتوری کاری جاری سنجیده می‌شود (نه نسبت به \f3path1\fR یا \f3path2\fR): .sp .nf \f3javadoc @path1/options @path2/packages\fP .fi .nf \f3\fP .fi .sp \f3مثال ۴: آرگومان‌های گزینه\fR .PP مثال زیر یک آرگومان مربوط به یکی از گزینه‌های دستور \f3javadoc\fR را در یک فایل آرگومان ذخیره می‌کند\&. از گزینهٔ \f3-bottom\fR استفاده شده زیرا می‌تواند آرگومانی طولانی داشته باشد\&. می‌توانید فایلی به نام bottom ایجاد کنید تا حاوی این آرگومان متنی باشد: .sp .nf \f3<font size="\-1">\fP .fi .nf \f3 <a href="http://bugreport\&.sun\&.com/bugreport">Submit a bug or feature</a><br/>\fP .fi .nf \f3 Copyright © 1993, 2011, Oracle and/or its affiliates\&. All rights reserved\&. <br/>\fP .fi .nf \f3 Oracle is a registered trademark of Oracle Corporation and/or its affiliates\&.\fP .fi .nf \f3 Other names may be trademarks of their respective owners\&.</font>\fP .fi .nf \f3\fP .fi .sp دستور \f3javadoc\fR را به صورت زیر اجرا کنید: \f3javadoc -bottom @bottom @packages\fR\&. .PP همچنین می‌توانید گزینهٔ \f3-bottom\fR را در ابتدای فایل آرگومان قرار دهید و دستور \f3javadoc\fR را به این صورت اجرا کنید: \f3javadoc @bottom @packages\fR\&..SH "اجرای دستور JAVADOC (RUNNING THE JAVADOC COMMAND)" شماره نسخهٔ دستور \f3javadoc\fR را می‌توان با گزینهٔ \f3javadoc -J-version\fR تعیین کرد\&. شماره نسخهٔ doclet استاندارد در جریان خروجی ظاهر می‌شود\&. این خروجی را می‌توان با گزینهٔ \f3-quiet\fR غیرفعال کرد\&. .PP برای فراخوانی دستور \f3javadoc\fR از درون برنامه‌های نوشته‌شده به زبان Java، از رابط برنامه‌نویسی عمومی (API) استفاده کنید\&. این رابط در \f3com\&.sun\&.tools\&.javadoc\&.Main\fR قرار دارد (و دستور \f3javadoc\fR قابلیت چندباره‌ورود یا reentrant دارد)\&. برای کسب اطلاعات بیشتر، The Standard Doclet را در http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/standard-doclet\&.html#runningprogrammatically ببینید\&. .PP دستورالعمل‌های زیر doclet استاندارد HTML را فراخوانی می‌کنند\&. برای فراخوانی یک doclet سفارشی، از گزینه‌های \f3-doclet\fR و \f3-docletpath\fR استفاده کنید\&. بخش Doclet Overview را در http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/doclet/overview\&.html ببینید\&. .SS "مثال‌های ساده (SIMPLE EXAMPLES)" می‌توانید دستور \f3javadoc\fR را روی تمام بسته‌ها یا روی فایل‌های سورس جداگانه اجرا کنید\&. هر نام بسته دارای یک نام دایرکتوری متناظر است\&. .PP در مثال‌های زیر، فایل‌های سورس در /home/src/java/awt/*\&.java قرار دارند\&. دایرکتوری مقصد /home/html است\&. .PP مستندسازی یک یا چند بسته برای مستندسازی یک بسته، فایل‌های سورس آن بسته باید در دایرکتوری‌ای قرار داشته باشند که نامی یکسان با بسته دارد\&. .PP اگر نام یک بسته دارای چندین شناسه باشد (که با نقطه جدا شده‌اند، مانند \f3java\&.awt\&.color\fR)، در این صورت هر شناسهٔ بعدی باید با یک زیردایرکتوری عمیق‌تر متناظر باشد (مانند java/awt/color)\&. .PP تا زمانی که \f3-sourcepath\fR به هر دو درخت اشاره کند، می‌توانید فایل‌های سورس یک بستهٔ واحد را بین دو درخت دایرکتوری واقع در مکان‌های مختلف تقسیم کنید\&. برای مثال، src1/java/awt/color و src2/java/awt/color\&. .PP می‌توانید دستور \f3javadoc\fR را یا با تغییر دایرکتوری (با دستور \f3cd\fR) یا با استفاده از گزینهٔ \f3-sourcepath\fR اجرا کنید\&. مثال‌های زیر هر دو روش را نشان می‌دهند\&. .PP \f3مثال ۱: اجرای بازگشتی از یک یا چند بسته\fR .PP این مثال از \f3-sourcepath\fR استفاده می‌کند تا دستور \f3javadoc\fR بتواند از هر دایرکتوری اجرا شود، و از \f3-subpackages\fR (گزینه‌ای جدید در نسخهٔ 1\&.4) برای اجرای بازگشتی بهره می‌برد\&. این دستور زیربسته‌های دایرکتوری java را پیمایش می‌کند، به استثنای بسته‌هایی که ریشه در \f3java\&.net\fR و \f3java\&.lang\fR دارند\&. توجه داشته باشید که این کار \f3java\&.lang\&.ref\fR را که زیربسته‌ای از \f3java\&.lang\fR است مستثنی می‌کند\&. برای پیمایش سایر درخت‌های بسته نیز می‌توانید نام آن‌ها را به آرگومان \f3-subpackages\fR اضافه کنید، مانند \f3java:javax:org\&.xml\&.sax\fR\&. .sp .nf \f3javadoc \-d /home/html \-sourcepath /home/src \-subpackages java \-exclude\fP .fi .nf \f3\fP .fi .sp \f3مثال ۲: تغییر به دایرکتوری ریشه و اجرای بسته‌های صریح\fR .PP به دایرکتوری والدِ بستهٔ کاملاً مشخص‌شده (fully qualified) بروید\&. سپس دستور \f3javadoc\fR را با نام یک یا چند بسته‌ای که می‌خواهید مستندسازی کنید اجرا نمایید: .sp .nf \f3cd /home/src/\fP .fi .nf \f3javadoc \-d /home/html java\&.awt java\&.awt\&.event\fP .fi .nf \f3\fP .fi .sp برای پیمایش سایر درخت‌های بسته نیز نام آن‌ها را به آرگومان \f3-subpackages\fR پیوست کنید، مانند \f3java:javax:org\&.xml\&.sax\fR\&. .PP \f3مثال ۳: اجرا از هر دایرکتوری روی بسته‌های صریح در یک درخت\fR .PP در این حالت، اهمیتی ندارد که دایرکتوری فعلی چه باشد\&. دستور \f3javadoc\fR را اجرا کرده و از گزینهٔ \f3-sourcepath\fR به همراه دایرکتوری والدِ بستهٔ سطح بالا (top-level) استفاده کنید\&. نام یک یا چند بسته‌ای را که می‌خواهید مستندسازی کنید مشخص نمایید: .sp .nf \f3javadoc \-d /home/html \-sourcepath /home/src java\&.awt java\&.awt\&.event\fP .fi .nf \f3\fP .fi .sp \f3مثال ۴: اجرا از هر دایرکتوری روی بسته‌های صریح در چندین درخت\fR .PP دستور \f3javadoc\fR را اجرا کرده و از گزینهٔ \f3-sourcepath\fR همراه با فهرستی از مسیرهای ریشهٔ هر درخت که با دونقطه (:) جدا شده‌اند استفاده نمایید\&. نام یک یا چند بسته‌ای را که می‌خواهید مستندسازی کنید مشخص کنید\&. نیازی نیست تمام فایل‌های سورس یک بستهٔ مشخص در یک دایرکتوری ریشهٔ واحد قرار داشته باشند، اما باید در جایی در طول مسیر سورس (source path) پیدا شوند\&. .sp .nf \f3javadoc \-d /home/html \-sourcepath /home/src1:/home/src2 java\&.awt java\&.awt\&.event\fP .fi .nf \f3\fP .fi .sp نتیجه این است که تمام حالت‌ها مستنداتی با ساختار HTML برای کلاس‌ها و رابط‌های \f3public\fR و \f3protected\fR در بسته‌های \f3java\&.awt\fR و \f3java\&.awt\&.event\fR تولید کرده و فایل‌های HTML را در دایرکتوری مقصدِ مشخص‌شده ذخیره می‌کنند\&. از آنجا که دو یا چند بسته در حال تولید هستند، سند دارای سه قاب (frame) تحت HTML خواهد بود: یکی برای فهرست بسته‌ها، دیگری برای فهرست کلاس‌ها، و سومی برای صفحات اصلی کلاس‌ها\&. .PP مستندسازی یک یا چند کلاس روش دوم برای اجرای دستور \f3javadoc\fR، ارسال یک یا چند فایل سورس است\&. می‌توانید \f3javadoc\fR را به یکی از دو روش زیر اجرا کنید: با تغییر دایرکتوری (با دستور \f3cd\fR) یا با مشخص کردن کامل مسیر فایل‌های سورس\&. مسیرهای نسبی نسبت به دایرکتوری فعلی سنجیده می‌شوند\&. هنگام ارسال فایل‌های سورس، گزینهٔ \f3-sourcepath\fR نادیده گرفته می‌شود\&. برای تعیین گروهی از کلاس‌ها می‌توانید از نویسه‌های عام خط فرمان، مانند ستاره (*)، استفاده کنید\&. .PP \f3مثال ۱: تغییر به دایرکتوری سورس\fR .PP به دایرکتوری حاوی فایل‌های سورس بروید\&. سپس دستور \f3javadoc\fR را با نام یک یا چند فایل سورسی که می‌خواهید مستندسازی کنید اجرا نمایید\&. .PP این مثال مستنداتی با ساختار HTML برای کلاس‌های \f3Button\fR، \f3Canvas\fR و کلاس‌هایی که با \f3Graphics\fR آغاز می‌شوند تولید می‌کند\&. از آنجا که به‌جای نام بسته‌ها، فایل‌های سورس به عنوان آرگومان به دستور \f3javadoc\fR داده شده‌اند، سند دارای دو قاب خواهد بود: یکی برای فهرست کلاس‌ها و دیگری برای صفحهٔ اصلی\&. .sp .nf \f3cd /home/src/java/awt\fP .fi .nf \f3javadoc \-d /home/html Button\&.java Canvas\&.java Graphics*\&.java\fP .fi .nf \f3\fP .fi .sp \f3مثال ۲: تغییر به دایرکتوری ریشهٔ بسته\fR .PP این روش برای مستندسازی فایل‌های سورس منفرد از زیربسته‌های مختلف که ریشهٔ یکسانی دارند مفید است\&. به دایرکتوری ریشهٔ بسته بروید و فایل‌های سورس را همراه با مسیرشان از ریشه مشخص نمایید\&. .sp .nf \f3cd /home/src/\fP .fi .nf \f3javadoc \-d /home/html java/awt/Button\&.java java/applet/Applet\&.java\fP .fi .nf \f3\fP .fi .sp \f3مثال ۳: مستندسازی فایل‌ها از هر دایرکتوری\fR .PP در این حالت، اهمیتی ندارد که دایرکتوری فعلی چه باشد\&. دستور \f3javadoc\fR را با مسیر مطلق (یا مسیر نسبی به دایرکتوری فعلی) فایل‌های سورسی که می‌خواهید مستندسازی کنید اجرا نمایید\&. .sp .nf \f3javadoc \-d /home/html /home/src/java/awt/Button\&.java\fP .fi .nf \f3/home/src/java/awt/Graphics*\&.java\fP .fi .nf \f3\fP .fi .sp .PP مستندسازی بسته‌ها و کلاس‌ها می‌توانید کل بسته‌ها و کلاس‌های منفرد را به طور هم‌زمان مستندسازی کنید\&. در اینجا مثالی ارائه شده که دو مورد از مثال‌های پیشین را ترکیب می‌کند\&. می‌توانید از گزینهٔ \f3-sourcepath\fR برای مسیر بسته‌ها استفاده کنید اما نه برای مسیر کلاس‌های منفرد\&. .sp .nf \f3javadoc \-d /home/html \-sourcepath /home/src java\&.awt\fP .fi .nf \f3/home/src/java/applet/Applet\&.java\fP .fi .nf \f3\fP .fi .sp.SS "مثال‌های کاربردی (REAL-WORLD EXAMPLES)" نسخه‌های خط فرمان و \f3makefile\fR زیر از دستور \f3javadoc\fR بر روی APIهای پلتفرم Java اجرا می‌شوند\&. این دستور برای تولید مستندات برای حدود ۱۵۰۰ کلاس public و protected در Java SE 1\&.2 به ۱۸۰ مگابایت حافظه نیاز دارد\&. هر دو مثال از مسیرهای مطلق در آرگومان‌های گزینه‌ها استفاده می‌کنند، به طوری که می‌توان همان دستور \f3javadoc\fR را از هر دایرکتوری اجرا کرد\&. .PP مثال خط فرمان دستور زیر ممکن است برای برخی از شل‌ها بیش از حد طولانی باشد\&. برای غلبه بر این محدودیت می‌توانید از یک فایل آرگومان خط فرمان استفاده کنید (یا یک اسکریپت شل بنویسید)\&. .PP در این مثال، \f3packages\fR نام فایلی است که بسته‌های مورد پردازش، مانند \f3java\&.applet\fR\f3java\&.lang\fR را در بر دارد\&. هیچ‌یک از گزینه‌ها نباید شامل نویسه خط جدید بین علامت‌های نقل‌قول تکی باشد\&. برای مثال، اگر این نمونه را رونوشت و جای‌گذاری می‌کنید، نویسه‌های خط جدید را از گزینه \f3-bottom\fR حذف کنید\&. .sp .nf \f3javadoc \-sourcepath /java/jdk/src/share/classes \e\fP .fi .nf \f3\-overview /java/jdk/src/share/classes/overview\&.html \e\fP .fi .nf \f3\-d /java/jdk/build/api \e\fP .fi .nf \f3\-use \e\fP .fi .nf \f3\-splitIndex \e\fP .fi .nf \f3\-windowtitle \&'Java Platform, Standard Edition 7 API Specification\&' \e\fP .fi .nf \f3\-doctitle \&'Java Platform, Standard Edition 7 API Specification\&' \e\fP .fi .nf \f3\-header \&'<b>Java\(tm SE 7</b>\&' \e\fP .fi .nf \f3\-bottom \&'<font size="\-1">\fP .fi .nf \f3<a href="http://bugreport\&.sun\&.com/bugreport">Submit a bug or feature</a><br/>\fP .fi .nf \f3Copyright © 1993, 2011, Oracle and/or its affiliates\&. All rights reserved\&.<br/>\fP .fi .nf \f3Oracle is a registered trademark of Oracle Corporation and/or its affiliates\&.\fP .fi .nf \f3Other names may be trademarks of their respective owners\&.</font>\&' \e\fP .fi .nf \f3\-group "Core Packages" "java\&.*:com\&.sun\&.java\&.*:org\&.omg\&.*" \e\fP .fi .nf \f3\-group "Extension Packages" "javax\&.*" \e\fP .fi .nf \f3\-J\-Xmx180m \e \fP .fi .nf \f3@packages\fP .fi .nf \f3\fP .fi .sp .PP رابط برنامه‌نویسی رابط Javadoc Access API کاربر را قادر می‌سازد تا ابزار Javadoc را مستقیماً از یک برنامه Java و بدون اجرای یک پردازش جدید فراخوانی کند\&. .PP برای مثال، عبارت‌های زیر معادل دستور \f3javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude java\&.net:java\&.lang com\&.example\fR هستند: .sp .nf \f3import javax\&.tools\&.DocumentationTool;\fP .fi .nf \f3import javax\&.tools\&.ToolProvider;\fP .fi .nf \f3\fP .fi .nf \f3public class JavaAccessSample{\fP .fi .nf \f3 public static void main(String[] args){\fP .fi .nf \f3 DocumentationTool javadoc = ToolProvider\&.getSystemDocumentationTool();\fP .fi .nf \f3 int rc = javadoc\&.run( null, null, null,\fP .fi .nf \f3 "\-d", "/home/html",\fP .fi .nf \f3 "\-sourcepath", "home/src",\fP .fi .nf \f3 "\-subpackages", "java",\fP .fi .nf \f3 "\-exclude", "java\&.net:java\&.lang",\fP .fi .nf \f3 "com\&.example");\fP .fi .nf \f3 }\fP .fi .nf \f3 }\fP .fi .nf \f3\fP .fi .sp سه آرگومان نخست متد \f3run\fR، جریان‌های ورودی، خروجی استاندارد و خطای استاندارد را مشخص می‌کنند\&. مقدار پیش‌فرض برای هر یک از \f3System\&.in\fR، \f3System\&.out\fR و \f3System\&.err\fR به ترتیب برابر با \f3Null\fR است\&. .SS "مثال MAKEFILE (THE MAKEFILE EXAMPLE)" این یک نمونه از یک \f3makefile\fR در GNU است\&. علامت‌های نقل‌قول تکی دور آرگومان‌های \f3makefile\fR قرار می‌گیرند\&. برای دیدن یک مثال از \f3makefile\fR ویندوز، بخش \f3makefiles\fR از Javadoc FAQ را در http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137483\&.html#makefiles ببینید\&. .sp .nf \f3javadoc \-sourcepath $(SRCDIR) \e /* Sets path for source files */\fP .fi .nf \f3 \-overview $(SRCDIR)/overview\&.html \e /* Sets file for overview text */\fP .fi .nf \f3 \-d /java/jdk/build/api \e /* Sets destination directory */\fP .fi .nf \f3 \-use \e /* Adds "Use" files */\fP .fi .nf \f3 \-splitIndex \e /* Splits index A\-Z */\fP .fi .nf \f3 \-windowtitle $(WINDOWTITLE) \e /* Adds a window title */\fP .fi .nf \f3 \-doctitle $(DOCTITLE) \e /* Adds a doc title */\fP .fi .nf \f3 \-header $(HEADER) \e /* Adds running header text */\fP .fi .nf \f3 \-bottom $(BOTTOM) \e /* Adds text at bottom */\fP .fi .nf \f3 \-group $(GROUPCORE) \e /* 1st subhead on overview page */\fP .fi .nf \f3 \-group $(GROUPEXT) \e /* 2nd subhead on overview page */\fP .fi .nf \f3 \-J\-Xmx180m \e /* Sets memory to 180MB */\fP .fi .nf \f3 java\&.lang java\&.lang\&.reflect \e /* Sets packages to document */\fP .fi .nf \f3 java\&.util java\&.io java\&.net \e\fP .fi .nf \f3 java\&.applet\fP .fi .nf \f3\fP .fi .nf \f3WINDOWTITLE = \&'Java\(tm SE 7 API Specification\&'\fP .fi .nf \f3DOCTITLE = \&'Java\(tm Platform Standard Edition 7 API Specification\&'\fP .fi .nf \f3HEADER = \&'<b>Java\(tm SE 7</font>\&'\fP .fi .nf \f3BOTTOM = \&'<font size="\-1">\fP .fi .nf \f3 <a href="http://bugreport\&.sun\&.com/bugreport">Submit a bug or feature</a><br/>\fP .fi .nf \f3 Copyright © 1993, 2011, Oracle and/or its affiliates\&. All rights reserved\&.<br/>\fP .fi .nf \f3 Oracle is a registered trademark of Oracle Corporation and/or its affiliates\&.\fP .fi .nf \f3 Other names may be trademarks of their respective owners\&.</font>\&'\fP .fi .nf \f3GROUPCORE = \&'"Core Packages" "java\&.*:com\&.sun\&.java\&.*:org\&.omg\&.*"\&'\fP .fi .nf \f3GROUPEXT = \&'"Extension Packages" "javax\&.*"\&'\fP .fi .nf \f3SRCDIR = \&'/java/jdk/1\&.7\&.0/src/share/classes\&'\fP .fi .nf \f3\fP .fi .sp.SS "نکات (NOTES)" .TP 0.2i \(bu اگر گزینهٔ \f3-windowtitle\fR را نادیده بگیرید، دستور \f3javadoc\fR عنوان سند را در عنوان پنجره کپی می‌کند\&. متن گزینهٔ \f3-windowtitle\fR شبیه به گزینهٔ \f3-doctitle\fR است، اما بدون برچسب‌های HTML تا از نمایش این برچسب‌ها به صورت متن خام در عنوان پنجره جلوگیری شود\&. .TP 0.2i \(bu اگر گزینهٔ \f3-footer\fR را نادیده بگیرید، دستور \f3javadoc\fR متن سربرگ را در پانویس کپی می‌کند\&. .TP 0.2i \(bu گزینه‌های مهم دیگری که ممکن است بخواهید استفاده کنید اما در مثال قبلی نیازی به آن‌ها نبود، گزینه‌های \f3-classpath\fR و \f3-link\fR هستند\&. .SH "عیب‌یابی عمومی (GENERAL TROUBLESHOOTING)" .TP 0.2i \(bu دستور \f3javadoc\fR تنها فایل‌هایی را می‌خواند که حاوی نام‌های معتبر کلاس باشند\&. اگر دستور \f3javadoc\fR محتویات یک فایل را به‌درستی نمی‌خواند، بررسی کنید که نام کلاس‌ها معتبر باشد\&. بخش Process Source Files را ببینید\&. .TP 0.2i \(bu برای اطلاعات در مورد باگ‌های رایج و نکات عیب‌یابی، پرسش‌های متداول Javadoc را در نشانی http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137483\&.html ببینید\&. .SH "خطاها و هشدارها (ERRORS AND WARNINGS)" پیام‌های خطا و هشدار به جای اشاره به خط خاصی در کامنت مستندسازی، حاوی نام فایل و شماره خط مربوط به اعلان هستند\&. .PP برای مثال، پیام \f3error: cannot read: Class1\&.java\fR به این معنی است که دستور \f3javadoc\fR در تلاش است تا \f3Class1\&.jav\fR\f3a\fR را در دایرکتوری جاری بارگذاری کند\&. نام کلاس به همراه مسیر آن (مطلق یا نسبی) نمایش داده می‌شود\&. .SH "محیط (ENVIRONMENT)" .TP CLASSPATH \f3CLASSPATH\fR متغیر محیطی است که مسیری را که دستور \f3javadoc\fR برای یافتن فایل‌های کلاس کاربری به کار می‌برد، فراهم می‌کند\&. این متغیر محیطی توسط گزینهٔ \f3-classpath\fR رونویسی (override) می‌شود\&. دایرکتوری‌ها را در Windows با یک نقطه‌ویرگول (semicolon) و در Oracle Solaris با یک دونقطه (colon) از هم جدا کنید\&. \fIمثال Windows\fR: \f3\&.;C:\eclasses;C:\ehome\ejava\eclasses\fR \fIمثال Oracle Solaris\fR: \f3\&.:/home/classes:/usr/local/java/classes\fR\&. .SH "همچنین ببینید (SEE ALSO)" .TP 0.2i \(bu javac(1) .TP 0.2i \(bu java(1) .TP 0.2i \(bu jdb(1) .TP 0.2i \(bu javap(1) .SH "اسناد مرتبط (RELATED DOCUMENTS)" .TP 0.2i \(bu فناوری Javadoc در http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/index\&.html .TP 0.2i \(bu نحوه پیدا شدن کلاس‌ها در http://docs\&.oracle\&.com/javase/8/docs/technotes/tools/findingclasses\&.html .TP 0.2i \(bu نحوه نوشتن کامنت‌های مستندسازی برای ابزار Javadoc در http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137868\&.html .TP 0.2i \(bu یادداشت URL، شناسه‌گرهای یکنواخت منبع در http://www\&.ietf\&.org/rfc/rfc1738\&.txt .TP 0.2i \(bu استاندارد HTML، نمایش سند HTML (۴۱۹۷۲۶۵ و ۴۱۳۷۳۲۱) http://www\&.w3\&.org/TR/REC-html40/charset\&.html#h-5\&.2\&.2 .RE .br 'pl 8.5i 'bp