'\" 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\&. اگر می‌خواهید زیربسته‌ها (subpackages) را نیز مستندسازی کنید، از گزینه \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 گزینه‌های خط فرمان، جدا شده با فاصله\&. بخش گزینه‌ها را ببینید\&. .TP \fI@argfiles\fR نام فایل‌هایی که حاوی فهرستی از گزینه‌های دستور \f3javadoc\fR، نام بسته‌ها و نام فایل‌های منبع به هر ترتیبی هستند\&. .SH "توضیحات (DESCRIPTION)" دستور \f3javadoc\fR اعلان‌ها و کامنت‌های مستندسازی را در مجموعه‌ای از فایل‌های منبع Java تجزیه کرده و مجموعه‌ای متناظر از صفحه‌های HTML تولید می‌کند که (به‌طور پیش‌فرض) کلاس‌های عمومی (public) و حفاظت‌شده (protected)، کلاس‌های تودرتو (اما نه کلاس‌های داخلی ناشناس)، رابط‌ها (interfaces)، سازنده‌ها (constructors)، متدها و فیلدها را توصیف می‌کنند\&. می‌توانید از دستور \f3javadoc\fR برای تولید مستندات API یا مستندات پیاده‌سازی برای مجموعه‌ای از فایل‌های منبع استفاده کنید\&. .PP می‌توانید دستور \f3javadoc\fR را روی تمام بسته‌ها، فایل‌های منبع منفرد، یا هر دو اجرا کنید\&. هنگام مستندسازی کل بسته‌ها، می‌توانید از گزینه \f3-subpackages\fR برای پیمایش بازگشتی یک دایرکتوری و زیردایرکتوری‌های آن استفاده کنید، یا فهرستی صریح از نام بسته‌ها را ارسال نمایید\&. هنگامی که فایل‌های منبع منفرد را مستندسازی می‌کنید، فهرستی از نام‌های فایل منبع Java را ارسال کنید\&. بخش مثال‌های ساده را ببینید\&. .SS "پردازش فایل‌های منبع (PROCESS SOURCE FILES)" دستور \f3javadoc\fR فایل‌هایی را که به منبع ختم می‌شوند و سایر فایل‌های توصیف‌شده در «فایل‌های منبع» را پردازش می‌کند\&. اگر دستور \f3javadoc\fR را با ارسال جداگانه نام فایل‌های منبع اجرا کنید، می‌توانید دقیقاً مشخص کنید که چه فایل‌های منبعی پردازش شوند\&. با این حال، بیشتر توسعه‌دهندگان مایل به این شیوه کار نیستند، چرا که ارسال نام بسته‌ها ساده‌تر است\&. دستور \f3javadoc\fR را می‌توان به سه روش بدون تعیین صریح نام فایل‌های منبع اجرا کرد: می‌توانید نام بسته‌ها را ارسال کنید، از گزینه \f3-subpackages\fR استفاده نمایید، یا از نویسه‌های عام همراه با نام فایل‌های منبع بهره بگیرید\&. در این حالت‌ها، دستور \f3javadoc\fR یک فایل منبع را تنها زمانی پردازش می‌کند که فایل تمام شرایط زیر را برآورده سازد: .TP 0.2i \(bu پیشوند نام فایل (پس از حذف \f3\&.java\fR) یک نام معتبر کلاس باشد\&. .TP 0.2i \(bu نام مسیر نسبت به ریشه درخت منبع، پس از تبدیل جداکننده‌ها به نقطه، یک نام معتبر بسته باشد\&. .TP 0.2i \(bu دستور package حاوی نام معتبر بسته باشد\&. .PP پردازش پیوندها در طول اجرا، دستور \f3javadoc\fR پیوندهای ارجاع متقابل (cross-reference) را به نام بسته‌ها، کلاس‌ها و اعضایی که در آن اجرا مستندسازی می‌شوند، اضافه می‌کند\&. پیوندها در مکان‌های زیر نمایش می‌یابند؛ برای توضیحات برچسب‌های @، برچسب‌های Javadoc را ببینید: .TP 0.2i \(bu اعلان‌ها (انواع بازگشتی، انواع آرگومان‌ها، و انواع فیلدها)\&. .TP 0.2i \(bu بخش‌های \fISee 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 به اعضای کلاس\&. به بخش توارث کامنت متد مراجعه کنید\&. .TP 0.2i \(bu جدول‌های خلاصه که بسته‌ها، کلاس‌ها و اعضا را فهرست می‌کنند\&. .TP 0.2i \(bu درخت‌های توارث بسته و کلاس\&. .TP 0.2i \(bu نمایه (index)\&. .PP می‌توانید با استفاده از گزینه‌های \f3-link\fR و \f3-linkoffline\fR، پیوندهایی به متن موجود برای کلاس‌هایی که در خط فرمان گنجانده نشده‌اند (اما به‌طور جداگانه تولید شده‌اند) اضافه کنید\&. .PP جزئیات پردازش دستور \f3javadoc\fR با هر بار اجرا، یک سند کامل تولید می‌کند\&. این دستور ساخت افزایشی (incremental build) انجام نمی‌دهد که نتایج اجراهای پیشین را اصلاح کرده یا مستقیماً ادغام کند\&. با این حال، دستور \f3javadoc\fR می‌تواند به نتایج حاصل از سایر اجراها پیوند برقرار نماید\&. .PP پیاده‌سازی دستور \f3javadoc\fR نیازمند و وابسته به کامپایلر Java است\&. دستور \f3javadoc\fR بخشی از دستور \f3javac\fR را فراخوانی می‌کند تا اعلان‌ها را کامپایل کرده و از پیاده‌سازی اعضا صرف‌نظر کند\&. دستور \f3javadoc\fR یک بازنمایی درونی غنی از کلاس‌ها می‌سازد که شامل سلسله‌مراتب کلاس‌ها و روابط استفاده برای تولید HTML است\&. دستور \f3javadoc\fR همچنین مستندات ارائه‌شده توسط کاربر را از کامنت‌های مستندسازی در کد منبع دریافت می‌کند\&. به بخش کامنت‌های مستندسازی مراجعه کنید\&. .PP دستور \f3javadoc\fR روی فایل‌های منبعی که فایل‌های ساختگی خالص (stub) بدون بدنه متد هستند نیز اجرا می‌شود\&. این بدان معناست که می‌توانید در مراحل اولیه طراحی و پیش از پیاده‌سازی API، کامنت‌های مستندسازی را بنویسید و دستور \f3javadoc\fR را اجرا کنید\&. .PP تکیه بر کامپایلر تضمین می‌کند که خروجی HTML دقیقاً با پیاده‌سازی واقعی مطابقت داشته باشد، که ممکن است متکی بر کد منبع ضمنی به جای صریح باشد\&. برای نمونه، دستور \f3javadoc\fR سازنده‌های پیش‌فرضی را که در فایل‌های کلاس کامپایل‌شده حضور دارند اما در کد منبع نیستند، مستندسازی می‌کند\&. .PP در بسیاری از موارد، دستور \f3javadoc\fR به شما اجازه می‌دهد برای فایل‌های منبع با کد ناقص یا خطا‌دار نیز مستندات تولید کنید\&. می‌توانید پیش از اتمام کامل اشکال‌زدایی و عیب‌یابی، مستندات را تولید نمایید\&. دستور \f3javadoc\fR بررسی‌های اولیه‌ای روی کامنت‌های مستندسازی انجام می‌دهد\&. .PP هنگامی که دستور \f3javadoc\fR ساختار درونی خود را برای مستندات می‌سازد، تمام کلاس‌های ارجاع داده شده را بارگذاری می‌کند\&. به همین دلیل، دستور \f3javadoc\fR باید بتواند تمام کلاس‌های ارجاع داده شده را بیابد، چه کلاس‌های راه‌اندازی (bootstrap)، افزونه‌ها، یا کلاس‌های کاربر\&. بخش «چگونگی یافتن کلاس‌ها» را در ببینید\&. .PP به‌طور معمول، کلاس‌هایی که ایجاد می‌کنید باید یا به عنوان یک افزونه بارگذاری شوند یا در مسیر کلاس (class path) دستور \f3javadoc\fR قرار گیرند\&..SS "داکلت‌های JAVADOC (JAVADOC DOCLETS)" شما می‌توانید محتوا و قالب خروجی دستور \f3javadoc\fR را با داکلت‌ها (doclets) سفارشی‌سازی کنید\&. دستور \f3javadoc\fR یک داکلت توکار پیش‌فرض به نام داکلت استاندارد دارد که مستندات API را در قالب HTML تولید می‌کند\&. شما می‌توانید داکلت استاندارد را تغییر داده یا از آن یک زیرکلاس (subclass) بسازید، یا داکلت اختصاصی خود را برای تولید خروجی در قالب‌های HTML، XML، MIF، RTF یا هر قالب دلخواه دیگری بنویسید\&. .PP هنگامی که یک داکلت سفارشی با گزینهٔ \f3-doclet\fR مشخص نشده باشد، دستور \f3javadoc\fR از داکلت استاندارد پیش‌فرض استفاده می‌کند\&. دستور \f3javadoc\fR چندین گزینه دارد که صرف‌نظر از داکلت مورد استفاده در دسترس هستند\&. داکلت استاندارد مجموعه‌ای تکمیلی از گزینه‌های خط فرمان را اضافه می‌کند\&. بخش «گزینه‌ها (Options)» را ببینید\&. .SH "فایل‌های منبع (SOURCE FILES)" دستور \f3javadoc\fR خروجی‌هایی تولید می‌کند که از انواع فایل‌های منبع زیر سرچشمه می‌گیرند: فایل‌های منبع زبان Java برای کلاس‌ها (\f3\&.java\fR)، فایل‌های توضیحات بسته، فایل‌های توضیحات کلی (overview)، و فایل‌های پردازش‌نشدهٔ متفرقه\&. این بخش همچنین فایل‌های آزمایشی و فایل‌های الگو را که ممکن است در درخت منبع وجود داشته باشند اما مایلید مستندسازی نشوند، شرح می‌دهد\&. .SS "فایل‌های منبع کلاس (CLASS SOURCE FILES)" هر کلاس یا رابط (interface) و اعضای آن می‌توانند توضیحات مستندسازی مخصوص به خود را در یک فایل منبع داشته باشند\&. بخش Documentation Comments را ببینید\&. .SS "فایل‌های توضیحات بسته (PACKAGE COMMENT FILES)" هر بسته می‌تواند توضیحات مستندسازی اختصاصی خود را در فایل منبع مربوطه‌اش داشته باشد که دستور \f3javadoc\fR آن را در صفحهٔ خلاصهٔ بستهٔ تولیدشده ادغام می‌کند\&. شما معمولاً هر مستنداتی را که برای کل بسته کاربرد دارد در این توضیحات قرار می‌دهید\&. .PP برای ایجاد یک فایل توضیحات بسته، می‌توانید توضیحات خود را در یکی از فایل‌های زیر قرار دهید: .TP 0.2i \(bu فایل \f3package-info\&.java\fR می‌تواند شامل اعلان بسته، حاشیه‌نویسی‌های (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) باشد\&. .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)" هر برنامه یا مجموعه‌ای از بسته‌ها که مستندسازی می‌کنید می‌تواند یادداشت توضیحی (کامنت) نمای کلیِ ویژه خود را داشته باشد که در فایل سورس جداگانه‌ای نگهداری می‌شود و دستور \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 و جمله اول، هیچ عنوان یا متن دیگری قرار ندهید\&. تمام تگ‌ها به جز تگ‌های درون‌خطی (inline)، مانند تگ {\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 به دایرکتوری مقصد کپی کند\&. این فایل‌ها معمولاً شامل فایل‌های گرافیکی، فایل‌های نمونه سورس و کلاس جاوا، و فایل‌های 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) .PP اگر می‌خواهید فایل‌های آزمون شما به یک بسته بدون نام یا به بسته‌ای غیر از بسته‌ای که فایل‌های سورس در آن قرار دارند تعلق داشته باشند، آن‌ها را در یک زیردایرکتوری زیر فایل‌های سورس قرار دهید و نام نامعتبری به آن دایرکتوری بدهید\&. اگر فایل‌های آزمون را در همان دایرکتوری سورس قرار دهید و دستور \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) .PP اگر می‌خواهید یک فایل الگو در دایرکتوری سورس باشد، اما هنگام اجرای دستور \f3javadoc\fR خطایی ایجاد نکند، یک نام فایل نامعتبر مانند \f3Buffer-Template\&.java\fR به آن بدهید تا از پردازش آن جلوگیری شود\&. دستور \f3javadoc\fR تنها فایل‌های سورسی را پردازش می‌کند که نام آن‌ها پس از حذف پسوند \f3\&.java\fR، نام معتبر یک کلاس باشد\&. .SH "فایل‌های تولیدشده (GENERATED FILES)" به طور پیش‌فرض، دستور \f3javadoc\fR از یک doclet استاندارد استفاده می‌کند که مستنداتی در قالب HTML تولید می‌کند\&. داکلت استاندارد صفحه‌های محتوای پایه، ارجاع متقابل و پشتیبانی را که در اینجا شرح داده شده‌اند تولید می‌نماید\&. هر صفحه HTML مربوط به یک فایل جداگانه است\&. دستور \f3javadoc\fR دو نوع فایل تولید می‌کند\&. نوع اول بر اساس کلاس‌ها و رابط‌ها (interfaces) نام‌گذاری می‌شود\&. نوع دوم برای جلوگیری از تداخل با نوع اول، شامل خط فاصله است (مانند 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 مشخص شده را می‌گنجاند\&. صفحه نمای کلی تنها زمانی ایجاد می‌شود که دو یا چند نام بسته را به دستور \f3javadoc\fR ارسال کنید\&. بخش‌های فریم‌های HTML و گزینه‌ها را ببینید\&. .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) که اطلاعاتی درباره کلاس‌های سریال‌پذیر (serializable) و اکسترنال‌پذیر (externalizable) به همراه توضیحات فیلدها و متدها ارائه می‌دهد\&. اطلاعات این صفحه برای بازپیاده‌سازی‌کنندگان مفید است و نه برای توسعه‌دهندگانی که می‌خواهند از API استفاده کنند\&. برای دسترسی به صفحه فرم سریالی‌شده، به هر کلاس سریالی‌شده رفته و روی \fISerialized Form\fR در بخش See Also کامنت کلاس کلیک کنید\&. داکلت استاندارد صفحه‌ای از فرم سریالی‌شده تولید می‌کند که هر کلاسی (عمومی یا غیرعمومی) را که Serializable را پیاده‌سازی کرده به همراه متدهای \f3readObject\fR و \f3writeObject\fR آن، فیلدهایی که سریال‌سازی می‌شوند و کامنت‌های مستندسازیِ تگ‌های \f3@serial\fR، \f3@serialField\fR و \f3@serialData\fR فهرست می‌کند\&. کلاس‌های سریال‌پذیر عمومی را می‌توان با علامت‌گذاری آن‌ها (یا بسته‌شان) با \f3@serial\fR exclude مستثنی کرد، و کلاس‌های سریال‌پذیر با سطح دسترسی بسته (package-private) را می‌توان با علامت‌گذاری با \f3@serial\fR include شامل نمود\&. از نگارش 1\&.4 به بعد، می‌توانید با اجرای دستور \f3javadoc\fR بدون مشخص کردن گزینه \f3-private\fR، فرم سریالی‌شده کامل را برای کلاس‌های عمومی و خصوصی تولید کنید\&. بخش گزینه‌ها را ببینید\&. .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) تولیدشده در همان سلسله‌مراتب دایرکتوری‌ای سازمان‌دهی می‌شوند که فایل‌های منبع و فایل‌های کلاس Java سازمان‌دهی شده‌اند\&. این ساختار شامل یک دایرکتوری به ازای هر زیربسته است\&. .PP به عنوان مثال، سند تولیدشده برای کلاس \f3java\&.applet\&.Applet\fR در مسیر java/applet/Applet\&.html قرار خواهد گرفت\&. .PP با این فرض که نام دایرکتوری مقصد \f3apidocs\fR باشد، ساختار فایل برای بسته \f3java\&.applet\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: رابط‌های برنامه‌نویسی منسوخ‌شده (Deprecated APIs) برای همه بسته‌ها .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 در ابتدای توضیحات هر کلاس، رابط، فیلد، سازنده و متد، یک اعلان برای آن بخش از 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 رابط‌های برنامه‌نویسی (APIها) به جای اتکا به کلمهٔ کلیدی \f3synchronized\fR، باید معناشناسی همزمانی خود را در توضیحات اصلی کامنت مستند کنند\&. برای مثال، یک توضیح می‌تواند به این صورت باشد: یک شمارشگر (enumeration) منفرد نمی‌تواند به‌طور همزمان توسط چندین ریسه به کار رود\&. مستندات نباید نحوهٔ دستیابی به این معناشناسی را شرح دهد\&. به عنوان مثالی دیگر، در حالی که گزینهٔ \f3Hashtable\fR باید برای ریسه‌ها امن (thread-safe) باشد، دلیلی ندارد تصریح شود که این امر با همگام‌سازی تمام متدهای صادرشدهٔ آن حاصل شده است\&. بهتر است حق همگام‌سازی داخلی در سطح bucket برای دستیابی به همزمانی بالاتر محفوظ بماند\&. .SH "کامنت‌های مستندسازی (DOCUMENTATION COMMENTS)" این بخش به شرح کامنت‌های کد منبع و وراثت کامنت‌ها می‌پردازد\&. .SS "کامنت‌های کد منبع (SOURCE CODE COMMENTS)" شما می‌توانید کامنت‌های مستندسازی را در کد منبع، پیش از اعلان‌های هر کلاس، رابط، متد، سازنده یا فیلد قرار دهید\&. همچنین می‌توانید برای هر بسته (package) و یک مورد نیز برای نمای کلی (overview) کامنت‌های مستندسازی ایجاد کنید، هرچند ساختار دستوری آن‌ها کمی متفاوت است\&. یک کامنت مستندسازی از نویسه‌های میان \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) یک کامنت مستندسازی دارای یک توضیحات اصلی و در ادامه یک بخش برچسب (tag) است\&. توضیحات اصلی پس از جداکنندهٔ ابتدایی \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 پردازش می‌شود\&. دو نوع برچسب وجود دارد: برچسب‌های بلوکی (block tags) که به صورت برچسب \f3@tag\fR ظاهر می‌شوند (همچنین به عنوان برچسب‌های مستقل یا standalone شناخته می‌شوند)، و برچسب‌های درون‌خطی (inline tags) که درون آکولادها به شکل برچسب \f3{@tag}\fR ظاهر می‌گردند\&. برای اینکه یک برچسب بلوکی تفسیر شود، باید در ابتدای یک سطر قرار گیرد (با نادیده گرفتن ستاره‌های ابتدایی، فاصله‌های خالی و جداکنندهٔ \f3/**\fR)\&. این بدان معناست که می‌توانید از نویسهٔ \f3@\fR در جاهای دیگر متن استفاده کنید و به عنوان آغاز یک برچسب تفسیر نخواهد شد\&. اگر می‌خواهید سطری را با نویسهٔ \f3@\fR آغاز کنید و نمی‌خواهید تفسیر شود، از نهاد اچ‌تی‌ام‌ال (HTML entity) \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 که مرورگرتان پشتیبانی می‌کند استفاده کنید\&. داکلت استاندارد (standard doclet) در سایر قسمت‌ها (خارج از کامنت‌های مستندسازی) کدی منطبق با HTML 3\&.2 به همراه شیوه‌نامه‌های آبشاری (CSS) و فریم‌ها تولید می‌کند\&. برای فایل‌های تولیدشده، نسخهٔ HTML 4\&.0 به دلیل مجموعه‌فریم‌ها (frame sets) ترجیح داده می‌شود\&. .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) پلتفرم Java به شما اجازه می‌دهد چندین فیلد را در یک عبارت واحد اعلان کنید، اما این عبارت تنها می‌تواند یک کامنت مستندسازی داشته باشد که برای تمام فیلدها کپی می‌شود\&. اگر کامنت‌های مستندسازی جداگانه‌ای برای هر فیلد می‌خواهید، هر فیلد را در یک عبارت مجزا اعلان کنید\&. برای مثال، کامنت مستندسازی زیر اگر به عنوان یک اعلان واحد نوشته شود بی‌معنی خواهد بود و بهتر است به عنوان دو اعلان مجزا مدیریت شود: .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 The horizontal and vertical distances of point (x, y)\&. .sp .nf \f3public int y\fP .fi .nf \f3\fP .fi .sp The horizontal and vertical distances of point (x, y)\&..PP استفاده از برچسب‌های سربرگ (Use of Header Tags) هنگام نوشتن یادداشت‌های مستندسازی برای اعضا، بهتر است از برچسب‌های سربرگ HTML مانند \f3<H1>\fR و \f3<H2>\fR استفاده نشود، زیرا دستور \f3javadoc\fR یک سند ساختاریافته کامل ایجاد می‌کند و این برچسب‌های ساختاری ممکن است با قالب‌بندی سند تولیدشده تداخل داشته باشند\&. با این حال، می‌توانید از این سربرگ‌ها در توضیحات کلاس‌ها و بسته‌ها برای ایجاد ساختار اختصاصی خود استفاده کنید\&. .SS "وراثت توضیحات متد (METHOD COMMENT INHERITANCE)" دستور \f3javadoc\fR امکان وراثت توضیحات متد را در کلاس‌ها و رابط‌ها برای پر کردن متن‌های جاافتاده یا به ارث بردن صریح توضیحات متد فراهم می‌کند\&. سازنده‌ها، فیلدها و کلاس‌های تو در تو یادداشت‌های مستندسازی را به ارث نمی‌برند\&. .PP \fIنکته:\fR فایل منبع متد موروثی باید در مسیری که توسط گزینه \f3\-sourcepath\fR مشخص شده است قرار داشته باشد تا یادداشت مستندسازی برای کپی شدن در دسترس باشد\&. نیازی نیست که کلاس یا بسته آن در خط فرمان وارد شود\&. این برخلاف نگارش 1\&.3\&.\fIn\fR و نگارش‌های پیشین است که در آن‌ها کلاس حتماً باید یک کلاس مستندشده می‌بود\&. .PP تکمیل متن‌های جاافتاده (Fill in Missing Text) هنگامی که توضیحات اصلی، یا برچسب‌های \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 (Javadoc Tags and Options) را ببینید\&. .PP وراثت صریح (Explicit Inheritance) برچسب درون‌خطی \f3{@inheritDoc}\fR را در توضیحات اصلی متد یا در توضیح برچسب‌های \f3@return\fR، \f3@param\fR یا \f3@throws\fR درج کنید\&. توضیحات اصلی موروثی یا توضیح برچسب متناظر در همان مکان کپی می‌شود\&. .SS "وراثت کلاس و رابط (CLASS AND INTERFACE INHERITANCE)" وراثت توضیحات در تمام حالت‌های ممکنِ وراثت از کلاس‌ها و رابط‌ها رخ می‌دهد: .TP 0.2i \(bu زمانی که یک متد در یک کلاس، متدی را در یک سوپرکلاس بازنویسی (override) می‌کند .TP 0.2i \(bu زمانی که یک متد در یک رابط، متدی را در یک سوپررابط بازنویسی می‌کند .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\&. در هر رابط مستقیماً پیاده‌سازی‌شده (یا ارث‌بری‌شده)، به ترتیبی که پس از کلمه \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 (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 برای برچسب‌های سفارشی، گزینه \-tag tagname:Xaoptcmf:"taghead" را ببینید\&. همچنین بخش 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\&. متن را با قلم کد بدون تفسیر متن به عنوان نشانه‌گذاری 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 را قبل از توضیحات اصلی قرار می‌دهد، آن را با قلم کج (italic) می‌آورد و هشداری پررنگ با عنوان Deprecated پیش از آن درج می‌کند\&. این برچسب در تمام یادداشت‌های مستندسازی معتبر است: overview، بسته، کلاس، رابط، سازنده، متد و فیلد\&. جمله اولِ متنِ منسوخ‌شدن باید به کاربر بگوید که این API در چه زمانی منسوخ شده و چه چیزی باید به عنوان جایگزین آن استفاده شود\&. دستور \f3javadoc\fR جمله اول را در بخش خلاصه و نمایه کپی می‌کند\&. جملات بعدی نیز می‌توانند دلیل منسوخ‌شدن را توضیح دهند\&. شما باید یک برچسب \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، بسته، کلاس، رابط، سازنده، متد و فیلد، و شامل بخش متنی هر برچسبی (مانند برچسب‌های \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 نیاز دارند\&. برای مثال، برنامه Inprise MAKE نسخه 5\&.2 که در 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 این برچسب به این دلیل لازم است که اسناد تولیدشده در دایرکتوری‌های سلسله‌مراتبی و با عمقی به اندازه تعداد زیربسته‌ها قرار دارند\&. عبارت: \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، بسته، کلاس، رابط، سازنده، متد و فیلد، شامل بخش متنی هر برچسب مانند برچسب‌های \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 است\&. هر دو برچسب به مراجع یکسانی نیاز دارند و نحو یکسانی را برای \f3package\&.class#member\fR و \f3label\fR می‌پذیرند\&. تفاوت اصلی در این است که برچسب \f3{@link}\fR به جای قرار دادن پیوند در بخش See Also، یک پیوند درون‌خطی ایجاد می‌کند\&. برچسب \f3{@link}\fR با آکولاد باز و بسته می‌شود تا از بقیه متنِ درون‌خطی متمایز گردد\&. اگر لازم است از آکولاد بسته (\f3}\fR) درون label استفاده کنید، نماد موجودیت 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 نمایش می‌دهد\&. این ویژگی شما را قادر می‌سازد تا از علامت‌های زاویه‌ای معمول (\f3< و >\fR) به جای موجودیت‌های HTML (\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 می‌افزاید\&. هنگام نوشتن کامنت مستندات، می‌توانید توضیحات را در چند سطر ادامه دهید\&. این برچسب فقط در کامنت مستندات یک متد، سازنده (constructor) یا کلاس معتبر است\&. بخش @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) از یک کلاس، متد یا سازنده باشد\&. برای مشخص کردن استفاده از پارامتر نوع، از براکت‌های شکسته (angle brackets) در دو طرف نام پارامتر استفاده کنید\&. مثالی از یک پارامتر نوع برای یک کلاس: .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، package، class، interface، constructor، method یا field\&. برای درج یک پیوند درون‌خطی در یک جمله به یک پکیج، کلاس یا عضو، \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 پیوندی همراه با یک برچسب متنیِ قابل مشاهده می‌افزاید که به مستندات نام مشخص‌شده و ارجاع‌یافته در زبان جاوا اشاره می‌کند\&. برچسب اختیاری است\&. در صورت حذف برچسب، نام به عنوان متن قابل مشاهده و به‌طور متناسب خلاصه‌شده نمایش می‌یابد\&. برای حذف سراسری نام پکیج از این متنِ قابل مشاهده، از گزینهٔ \f3-noqualifier\fR استفاده کنید\&. زمانی از برچسب استفاده کنید که می‌خواهید متن قابل مشاهده با متن تولیدشدهٔ خودکار متفاوت باشد\&. بخش How a Name Appears را ببینید\&. تنها در Java SE 1\&.2، نام (نه برچسب) به‌طور خودکار درون برچسب‌های اچ‌تی‌ام‌ال \f3<code>\fR قرار می‌گرفت\&. با شروع از Java SE 1\&.2\&.2، برچسب \f3<code>\fR همواره در اطراف متن قابل مشاهده قرار می‌گیرد، خواه از برچسب (label) استفاده شده باشد خواه نشده باشد\&. .RS .TP 0.2i \(bu عبارت \f3package\&.class#member\fR هر نام معتبری از عناصر برنامه است که به آن ارجاع داده می‌شود، مانند نام پکیج، کلاس، رابط، سازنده، متد یا فیلد؛ جز اینکه نویسهٔ پیش از نام عضو باید علامت هش (\f3#\fR) باشد\&. بخش class نمایانگر هر کلاس یا رابط سطح بالا (top-level) یا تودرتو (nested) است\&. بخش member نمایانگر هر سازنده، متد، یا فیلد است (نه یک کلاس یا رابط تودرتو)\&. اگر این نام در کلاس‌های مستندسازی‌شده باشد، دستور \f3javadoc\fR پیوندی به آن ایجاد می‌کند\&. برای ایجاد پیوند به کلاس‌های ارجاع‌داده‌شدهٔ خارجی، از گزینهٔ \f3-link\fR استفاده کنید\&. برای ارجاع به مستندات نامی که متعلق به یک کلاس ارجاع‌شده نیست، از یکی از دو فرم دیگر برچسب \f3@see\fR استفاده کنید\&. بخش Specify a Name را ببینید\&. \fIنکته:\fR کلاس‌های ارجاع‌داده‌شدهٔ خارجی کلاس‌هایی هستند که در خط فرمان به دستور \f3javadoc\fR ارسال نشده‌اند\&. پیوندهای موجود در مستندات تولیدشده به کلاس‌های ارجاع‌داده‌شدهٔ خارجی، ارجاعات خارجی یا پیوندهای خارجی نامیده می‌شوند\&. برای نمونه، اگر دستور \f3javadoc\fR را فقط روی پکیج \f3java\&.awt\fR اجرا کنید، هر کلاسی در \f3java\&.lang\fR، مانند \f3Object\fR، یک کلاس ارجاع‌داده‌شدهٔ خارجی است\&. برای پیوند دادن به کلاس‌های ارجاع‌داده‌شدهٔ خارجی از گزینه‌های \f3-link\fR و \f3-linkoffline\fR استفاده کنید\&. کامنت‌های سورس‌کد کلاس‌های ارجاع‌داده‌شدهٔ خارجی در دسترس اجرای دستور \f3javadoc\fR نیستند\&. .TP 0.2i \(bu مقدار \f3label\fR متنی اختیاری است که به عنوان برچسب پیوند قابل مشاهده است\&. برچسب می‌تواند حاوی فضای خالی باشد\&. اگر \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 می‌تواند کاملاً مشخص‌شده (fully qualified) باشد، مانند \f3java\&.lang\&.String#toUpperCase()\fR، یا خیر، مانند \f3String#toUpperCase()\fR یا \f3#toUpperCase()\fR\&. اگر نام کمتر از حالت کاملاً مشخص‌شده باشد، دستور \f3javadoc\fR از ترتیب جستجوی استاندارد کامپایلر جاوا برای یافتن آن استفاده می‌کند\&. بخش Search Order for the @see Tag را ببینید\&. نام می‌تواند در داخل پرانتزها حاوی فضای خالی باشد، مانند فاصله‌های میان آرگومان‌های متد\&. مزیت ارائهٔ نام‌های کوتاه‌تر و نیمه‌مشخص (partially qualified) این است که تایپ کردن آن‌ها کوتاه‌تر بوده و شلوغی کمتری در کد مبدأ ایجاد می‌شود\&. فهرست زیر فرم‌های گوناگون نام را نشان می‌دهد، که در آن \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) باید برای تمام قالب‌ها به‌صورت \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 را که در یک فایل مبدأ، فایل بسته یا فایل مرور کلی (overview) ظاهر می‌شود، پردازش می‌کند\&. در دو فایل آخر، باید نامی را که همراه با برچسب \f3@see\fR ارائه می‌دهید، به‌طور کامل واجد شرایط (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\fR ارجاع دهد، دستور \f3javadoc\fR در آن بسته جستجو نمی‌کند مگر اینکه آن کلاس، بسته مزبور را وارد کرده باشد\&. .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-link\fR برچسب \f3@see\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 اختیاری باید معنای فیلد را توضیح داده و مقادیر مجاز را فهرست کند\&. در صورت نیاز، توضیحات می‌تواند چندین خط را در بر گیرد\&. داک‌لت (doclet) استاندارد این اطلاعات را به صفحه فرمت سریالی‌شده می‌افزاید\&. بخش «صفحات ارجاع متقابل» را ببینید\&. اگر یک فیلد سریال‌پذیر پس از اینکه کلاس سریال‌پذیر شد به آن اضافه شده باشد، باید جمله‌ای به توضیحات اصلی آن افزوده شود تا مشخص کند در کدام نسخه اضافه شده است\&. آرگومان‌های \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 با برچسب \f3@serial exclude\fR در package\&.html یا package-info\&.java نشانه‌گذاری شده است\&. کلاس عمومی \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 از مقدار شرح داده برای مستندسازی نوع‌ها و ترتیب داده‌ها در فرمت سریالی‌شده استفاده می‌کند\&. این داده‌ها شامل داده‌های اختیاری نوشته‌شده توسط متد \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 به مستندات تولیدشده می‌افزاید\&. این متن هیچ ساختار درونی خاصی ندارد\&. این برچسب در هر کامنت مستندسازی معتبر است: مرور کلی، بسته، کلاس، رابط، سازنده، متد یا فیلد\&. این برچسب بدین معناست که این تغییر یا ویژگی از زمان انتشار نرم‌افزاری که با مقدار \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 .PP هنگامی که گزینهٔ \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 ببینید\&. .PP یک کامنت مستندسازی می‌تواند شامل چندین برچسب \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 \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 از داکلت‌ها (doclet) برای تعیین خروجی خود استفاده می‌کند\&. دستور \f3javadoc\fR از داکلت استاندارد پیش‌فرض استفاده می‌کند، مگر اینکه با استفاده از گزینه \f3-doclet\fR یک داکلت سفارشی مشخص شود\&. دستور \f3javadoc\fR مجموعه‌ای از گزینه‌های خط فرمان را ارائه می‌دهد که می‌توان آن‌ها را با هر داکلتی به کار برد\&. این گزینه‌ها در بخش Javadoc Options شرح داده شده‌اند\&. داکلت استاندارد مجموعه دیگری از گزینه‌های خط فرمان را ارائه می‌دهد که در بخش Standard Doclet Options شرح داده شده‌اند\&. تمامی نام‌های گزینه‌ها به حروف کوچک و بزرگ حساس نیستند، اما آرگومان‌های آن‌ها به حروف کوچک و بزرگ حساس هستند\&. .TP 0.2i \(bu همچنین بخش Javadoc Options را ببینید .TP 0.2i \(bu همچنین بخش Standard Doclet Options را ببینید .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 باید متن مستندات کلی را از فایل مبدأ مشخص‌شده توسط \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 هشدارهایی را برای ارجاعات نادرست، عدم دسترسی‌پذیری و کامنت‌های مفقود Javadoc، و خطاهایی را برای نحو نامعتبر Javadoc و تگ‌های مفقود HTML گزارش می‌دهد\&. این گزینه دستور \f3javadoc\fR را قادر می‌سازد تا تمامی کامنت‌های مستندسازی گنجانده‌شده در خروجی تولیدی را بررسی کند\&. طبق معمول، می‌توانید با استفاده از گزینه‌های استاندارد \f3-public\fR، \f3-protected\fR، \f3-package\fR و \f3-private\fR تعیین کنید کدام موارد در خروجی تولیدی قرار گیرند\&. هنگامی که \f3-Xdoclint\fR فعال باشد، مشکلات را با پیام‌هایی مشابه دستور \f3javac\fR گزارش می‌دهد\&. دستور \f3javadoc\fR یک پیام، رونوشتی از خط مبدأ و یک علامت هشتک (caret) که به موقعیت دقیق شناسایی خطا اشاره دارد را چاپ می‌کند\&. پیام‌ها بسته به شدت و احتمال ایجاد خطا در صورتی که مستندات تولیدشده توسط یک اعتبارسنج بررسی شوند، ممکن است هشدار یا خطا باشند\&. برای مثال، ارجاعات نادرست یا کامنت‌های مفقود 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 : مشکلات مربوط به ارجاعات تگ‌های Javadoc به عناصر Java API را بررسی می‌کند (برای مثال، یافت نشدن مورد در \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 نیست\&. هدف گزینه -\f3Xdoclint\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 نسخه (release) کد مبدأ پذیرفته‌شده را مشخص می‌کند\&. مقادیر زیر برای پارامتر \f3release\fR مجاز هستند\&. از مقدار \f3release\fR متناظر با مقداری که هنگام کامپایل کد با دستور \f3javac\fR استفاده می‌کنید، بهره ببرید\&. .RS .TP 0.2i \(bu \fIRelease Value: 1\&.5\fR\&. دستور \f3javadoc\fR کدهای شامل نوع‌های عمومی (generics) و سایر ویژگی‌های زبان معرفی‌شده در JDK 1\&.5 را می‌پذیرد\&. هنگامی که از گزینه \f3-source\fR استفاده نشود، رفتار کامپایلر به‌طور پیش‌فرض مطابق با 1\&.5 خواهد بود\&. .TP 0.2i \(bu \fIRelease Value: 1\&.4\fR\&. دستور \f3javadoc\fR کدهای حاوی assertionها را که در JDK 1\&.4 معرفی شده‌اند می‌پذیرد\&. .TP 0.2i \(bu \fIRelease Value: 1\&.3\fR\&. دستور \f3javadoc\fR از assertionها، generics یا سایر ویژگی‌های زبان که پس از 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 از class path برای یافتن فایل‌های مبدأ استفاده می‌کند (گزینه \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) است که نیازی به داشتن فایل‌های منبع ندارد\&. آرگومان‌ها در تمام سیستم‌های عامل با دو‌نقطه (:) از هم جدا می‌شوند\&. استفاده از نویسه‌های عمومی (Wildcardها) مجاز نیست\&. برای تعیین محل یافتن بسته‌ها از \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 mechanism) استفاده می‌کند\&. گزینهٔ \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 را هنگام تولید مستندات تعیین می‌کند\&. آرگومان، نام محلی‌سازی است، همان‌گونه که در مستندات \f3java\&.util\&.Locale\fR شرح داده شده است، مانند \f3en_US\fR (انگلیسی، ایالات متحده) یا \f3en_US_WIN\fR (گونهٔ ویندوز)\&. \fIنکته:\fR گزینهٔ \f3-locale\fR باید جلوتر (در سمت چپ) هر گزینهٔ ارائه‌شده توسط doclet استاندارد یا هر doclet دیگری قرار گیرد\&. در غیر این صورت، نوارهای ناوبری به زبان انگلیسی نمایش داده می‌شوند\&. این تنها گزینهٔ خط فرمانی است که عملکرد آن به ترتیب قرارگیری وابسته است\&. بخش «گزینه‌های استاندارد Doclet» (Standard Doclet Options) را ببینید\&. تعیین یک محلی‌سازی باعث می‌شود دستور \f3javadoc\fR فایل‌های منبع (resource files) آن محلی‌سازی را برای پیام‌هایی مانند رشته‌های موجود در نوار ناوبری، سربرگ‌های فهرست‌ها و جدول‌ها، محتوای فایل‌های راهنما، توضیحات موجود در فایل stylesheet\&.css و غیره انتخاب کند\&. همچنین ترتیب مرتب‌سازی برای فهرست‌های مرتب‌شده بر اساس حروف الفبا و جداکنندهٔ جمله را برای تعیین پایان اولین جمله مشخص می‌سازد\&. گزینهٔ \f3-locale\fR محلی‌سازی متن توضیحات مستندات مشخص‌شده در فایل‌های منبع کلاس‌های مستندشده را تعیین نمی‌کند\&. .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 استاندارد در جریان خروجی آن نمایش می‌یابد\&. بخش «اجرای دستور Javadoc» (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\fR\f3/user/doc/\fR\f3com\&.mypackage\fR\&. .TP -use .br یک صفحهٔ «استفاده» (Use page) برای هر کلاس و بستهٔ مستندشده ایجاد می‌کند\&. این صفحه مشخص می‌کند چه بسته‌ها، کلاس‌ها، متدها، سازنده‌ها و فیلدهایی از هرگونه API کلاس یا بستهٔ مشخص‌شده استفاده می‌کنند\&. با فرض کلاس C، مواردی که از کلاس C استفاده می‌کنند شامل زیرکلاس‌های C، فیلدهای اعلان‌شده از نوع C، متدهایی که C را برمی‌گردانند، و متدها و سازنده‌هایی با پارامترهایی از نوع C خواهند بود\&. برای مثال، می‌توانید به صفحهٔ Use برای نوع \f3String\fR نگاه کنید\&. از آنجا که متد \f3getName\fR در کلاس \f3java\&.awt\&.Font\fR نوع \f3String\fR را برمی‌گرداند، متد \f3getName\fR از \f3String\fR استفاده می‌کند و بنابراین متد \f3getName\fR در صفحهٔ Use مربوط به \f3String\fR ظاهر می‌شود\&. این گزینه تنها کاربردهای API را مستند می‌کند، نه پیاده‌سازی را\&. اگر متدی در پیاده‌سازی داخلی خود از \f3String\fR استفاده کند، اما رشته‌ای را به عنوان آرگومان دریافت نکند یا برنگرداند، استفاده از \f3String\fR در نظر گرفته نمی‌شود\&. برای دسترسی به صفحهٔ Use تولیدشده، به کلاس یا بسته رفته و روی پیوند \fIUse link\fR در نوار ناوبری کلیک کنید\&. .TP -version .br متن @version را در مستندات تولیدشده می‌گنجاند\&. این متن به‌طور پیش‌فرض حذف می‌شود\&. برای اطلاع از نسخهٔ دستور \f3javadoc\fR مورد استفاده، از گزینهٔ \f3-J-version\fR استفاده کنید\&. .TP -author .br متن \f3@author\fR را در مستندات تولیدشده می‌گنجاند\&. .TP -splitindex .br فایل نمایه (index) را به چندین فایل، به‌ترتیب الفبا و یک فایل به ازای هر حرف، به علاوهٔ یک فایل برای مدخل‌های نمایه‌ای که با نمادهای غیرالفبایی آغاز می‌شوند، تقسیم می‌کند\&. .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 عنوانی را مشخص می‌کند که در نزدیکی بالای فایل خلاصهٔ کلی (overview summary) قرار می‌گیرد\&. متن مشخص‌شده در برچسب \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 و فاصلهٔ خالی باشد، اما در این صورت، \f3header\fR باید در نشانه‌های نقل‌قول محصور شود\&. برای علامت‌های نقل‌قول درونی در سرآیند از نویسه‌های گریز استفاده کنید\&. برای مثال، \f3javadoc -header "<b>Java Platform </b><br>v1\&.4" com\&.mypackage\&.\fR .TP -footer \fIfooter\fR .br متن پاورقی را مشخص می‌کند که در پایین هر فایل خروجی قرار می‌گیرد\&. مقدار \fIfooter\fR در سمت راست نوار ناوبری پایینی قرار می‌گیرد\&. مقدار \f3footer\fR می‌تواند حاوی برچسب‌های HTML و فاصلهٔ خالی باشد، اما در این صورت، مقدار \f3footer\fR باید در نشانه‌های نقل‌قول محصور شود\&. برای هرگونه علامت نقل‌قول درونی در پاورقی از نویسه‌های گریز استفاده کنید\&. .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 می‌خواند و به آن بسته‌ها در آن نشانی وب پیوند می‌دهد\&. هنگام اجرای دستور \f3javadoc\fR، مقدار \f3extdocURL\fR در پیوندهای \f3<A HREF>\fR ایجادشده رونوشت می‌شود\&. بنابراین، \f3extdocURL\fR باید نشانی وب یک دایرکتوری باشد نه یک فایل\&. می‌توانید از یک پیوند مطلق برای \fIextdocURL\fR استفاده کنید تا اسناد شما بتوانند به سندی در هر وب‌سایتی پیوند برقرار کنند، یا می‌توانید از یک پیوند نسبی برای پیوند منحصراً به یک مکان نسبی بهره بگیرید\&. اگر از پیوند نسبی استفاده می‌کنید، مقداری که ارسال می‌کنید باید مسیر نسبی از دایرکتوری مقصد (مشخص‌شده با گزینهٔ \f3-d\fR) به دایرکتوری حاوی بسته‌های پیوند داده شده باشد\&. وقتی یک پیوند مطلق را مشخص می‌کنید، معمولاً از پیوند HTTP استفاده می‌نمایید\&. با این حال، اگر می‌خواهید به سیستم فایلی پیوند برقرار کنید که کارساز وب ندارد، می‌توانید از پیوند فایل (file link) استفاده کنید\&. تنها زمانی از پیوند فایل استفاده کنید که همهٔ کسانی که قصد دسترسی به مستندات تولیدشده را دارند از همان سیستم فایل مشترک استفاده کنند\&. در تمام موارد و در تمام سیستم‌های عامل، چه نشانی وب مطلق باشد یا نسبی، از ممیز (/) به عنوان جداکننده استفاده کنید و پروتکل‌های \f3http:\fR یا \f3file:\fR را همان‌گونه که در یادداشت Uniform Resource Locators در http://www\&.ietf\&.org/rfc/rfc1738\&.txt مشخص شده است، به کار ببرید\&. .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 زمانی که از یک نشانی وب مطلق به سند API خارجی استفاده می‌کنید و پوستهٔ شما اجازهٔ برقراری ارتباط با آن نشانی وب را برای خواندن می‌دهد\&..PP هنگامی که از یک URL مطلق برای سند API خارجی استفاده می‌کنید، اگر شل شما اجازه باز کردن اتصال به آن URL را جهت خواندن به برنامه نمی‌دهد، از گزینه \f3-linkoffline\fR استفاده کنید\&. این حالت زمانی می‌تواند رخ دهد که پشت یک فایروال قرار دارید و سندی که می‌خواهید به آن پیوند دهید در سمت دیگر قرار دارد\&. .PP \f3مثال ۱ پیوند مطلق به اسناد خارجی\fR .PP اگر می‌خواهید به بسته‌های پلتفرم Java مانند \f3java\&.lang\fR، \f3java\&.io\fR و سایر بسته‌های نمایش‌داده‌شده در 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 را ببینید\&. کاربرد دیگر آن برای ایجاد پیوندهای متقابل بین مجموعه‌هایی از بسته‌ها است: دستور \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 این ارجاع می‌تواند در نوع بازگشتی یا نوع پارامتر یک متد، سازنده، فیلد، کلاس یا واسط (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 برای نمونه، فهرست بسته‌ها برای API جاوا SE در 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 را برای پیوند دادن به هر تعداد سند تولیدشده خارجی ارائه دهید\&. نسخه 1\&.2 برنامه Javadoc دارای یک باگ شناخته‌شده بود که از ارائه بیش از یک گزینه \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 را شامل نکنید\&. می‌توانید در یک اجرای مشخص از دستور \f3javadoc\fR چندین گزینه \f3-linkoffline\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 را روی کل درخت کد منبع اجرا کرده‌اید، می‌توانید به سرعت تغییرات کوچکی در کامنت‌های مستندسازی ایجاد کنید و دستور \f3javadoc\fR را دوباره روی بخشی از درخت منبع اجرا نمایید\&. توجه داشته باشید که اجرای دوم تنها در صورتی به درستی کار می‌کند که تغییرات شما مربوط به کامنت‌های مستندسازی باشد و نه اعلان‌ها\&. اگر هر گونه اعلانی را به کد منبع اضافه، حذف یا تغییر دهید، ممکن است پیوندهای شکسته در فهرست راهنما، درخت بسته، فهرست اعضای ارث‌بری‌شده، صفحه 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 می‌تواند هر متنی باشد و می‌تواند شامل فاصله خالی نیز باشد\&. این متن در سربرگ جدول برای آن گروه قرار می‌گیرد\&..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 مسیر یک فایل راهنمای جایگزین path\efilename را مشخص می‌کند که پیوند 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 هشدارهای زمان ترجمه (compile-time) را برای برچسب‌های فراموش‌شده \f3@serial\fR تولید می‌کند\&. به‌طور پیش‌فرض، Javadoc 1\&.2\&.2 و نسخه‌های بعدی هیچ هشدار سریالی‌سازی (serial) تولید نمی‌کنند\&. این رفتار نسبت به نگارش‌های پیشین تغییر یافته است\&. از این گزینه برای نمایش هشدارهای serial استفاده کنید که به مستندسازی مناسب فیلدهای سریال‌پذیر پیش‌فرض و متدهای \f3writeExternal\fR کمک می‌کند\&. .TP -charset \fIname\fR .br مجموعه‌نویسه (character set) زبان HTML را برای این سند مشخص می‌کند\&. نام باید یک نام ترجیحی MIME باشد، همان‌طور که در IANA Registry تحت عنوان Character Sets در نشانی 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 (شماره‌های 4197265 و 4137321)، بخش 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 Registry تحت عنوان Character Sets در نشانی 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 name) کلاس و نام‌های ساده و بدون پیشوند فیلدها و متدها هستند\&. سازنده‌ها (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 را به‌صورت پررنگ خروجی می‌دهد و به دنبال آن در خط بعدی متن آرگومان تکی آن قرار می‌گیرد\&. مشابه هر برچسب بلوکی دیگر، متن آرگومان می‌تواند حاوی برچسب‌های درون‌خطی (inline) باشد که آن‌ها نیز تفسیر می‌شوند\&. خروجی مشابه برچسب‌های استاندارد تک‌آرگومانی مانند برچسب‌های \f3@return\fR و \f3@author\fR است\&. حذف مقدار برای \fItaghead\fR باعث می‌شود \f3tagname\fR به عنوان عنوان قرار گیرد\&. \fIمحل قرارگیری برچسب‌ها\fR: آرگومان‌های \f3Xaoptcmf\fR مشخص می‌کنند که برچسب در کجای کد منبع مجاز به قرارگیری است و اینکه آیا برچسب می‌تواند غیرفعال شود (با استفاده از \f3X\fR) یا خیر\&. می‌توانید \f3a\fR را برای مجاز کردن برچسب در همه مکان‌ها مشخص کنید، یا ترکیبی از سایر حروف را به کار ببرید: \f3X\fR (غیرفعال کردن برچسب) \f3a\fR (همه جا) \f3o\fR (نمای کلی - overview) \f3p\fR (بسته‌ها - packages) \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 برچسبی است که می‌خواهید در خروجی متوقف (suppress) شود، از این قالب استفاده کنید: \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: اگر می‌خواهید فضای نام اختصاصی خود را ایجاد کنید، می‌توانید از یک قرارداد نام‌گذاری جداشده با نقطه مشابه آنچه برای بسته‌ها به کار می‌رود استفاده کنید: \f3com\&.mycompany\&.todo\fR\&. شرکت Oracle به ایجاد برچسب‌های استانداردی که نام آن‌ها حاوی نقطه نیست ادامه خواهد داد\&. هر برچسبی که ایجاد کنید رفتار برچسبی با همان نام را که توسط Oracle تعریف شده لغو و بازنویسی می‌کند\&. اگر یک برچسب یا 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 فایل کلاسی را مشخص می‌کند که تگلتی را آغاز می‌کند که برای تولید مستندات برای آن تگ استفاده می‌شود\&. برای مقدار \f3class\fR از نام کامل واجد شرایط (fully qualified name) استفاده کنید\&. این تگلت همچنین تعداد آرگومان‌های متنی را که تگ سفارشی دارد مشخص می‌کند\&. تگلت این آرگومان‌ها را دریافت کرده، آن‌ها را پردازش می‌کند و خروجی را تولید می‌نماید\&. برای مستندات جامع به همراه نمونه‌های تگلت، ببینید: Taglet Overview در http://docs\&.oracle\&.com/javase/8/docs/technotes/guides/javadoc/taglet/overview\&.html تگلت‌ها برای تگ‌های بلوکی یا درون‌خطی مفید هستند\&. آن‌ها می‌توانند هر تعداد آرگومان داشته باشند و رفتارهای سفارشی را پیاده‌سازی کنند، مانند پررنگ (bold) کردن متن، قالب‌بندی بالت‌ها، نوشتن متن در یک فایل، یا آغاز فرایندهای دیگر\&. تگلت‌ها فقط می‌توانند تعیین کنند که یک تگ در کجا و به چه شکلی نمایش یابد\&. تمام تصمیمات دیگر توسط doclet گرفته می‌شود\&. یک تگلت نمی‌تواند کارهایی مانند حذف یک نام کلاس از فهرست کلاس‌های گنجانده‌شده را انجام دهد\&. با این حال، می‌تواند اثرات جانبی (side effects) را اجرا کند، مانند چاپ متن تگ در یک فایل یا فعال‌سازی فرایندی دیگر\&. از گزینهٔ \f3-tagletpath\fR برای تعیین مسیر تگلت استفاده کنید\&. مثال زیر تگلت To Do را پس از Parameters و پیش از Throws در صفحات تولیدشده درج می‌کند\&. همچنین، می‌توانید به جای گزینهٔ \f3-tag\fR از گزینهٔ \f3-taglet\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 کپی عمیق دایرکتوری‌های doc-files را فعال می‌کند\&. زیردایرکتوری‌ها و تمام محتویات به‌صورت بازگشتی در مقصد کپی می‌شوند\&. برای مثال، دایرکتوری doc-files/example/images و تمام محتویات آن کپی خواهد شد\&. همچنین گزینه‌ای برای مستثنی کردن زیردایرکتوری‌ها وجود دارد\&. .TP -excludedocfilessubdir \fIname1:name2\fR .br هر زیردایرکتوری doc-files با نام‌های مشخص‌شده را مستثنی می‌کند\&. این کار از کپی شدن دایرکتوری‌های SCCS و سایر زیردایرکتوری‌های سامانهٔ کنترل کد مبدأ جلوگیری می‌نماید\&. .TP -noqualifier all | \fIpackagename1\fR:\fIpackagename2\&.\&.\&.\fR .br نام‌های بسته‌های واجد شرایط (qualifiers) را از نام کلاس‌ها در خروجی حذف می‌کند\&. آرگومان گزینهٔ \f3-noqualifier\fR یا \f3all\fR است (تمام واجد‌کننده‌های بسته حذف می‌شوند) یا فهرستی جداشده با دونقطه از بسته‌ها به همراه نویسه‌های عام (wildcard) است که باید به عنوان واجد‌کننده حذف شوند\&. نام بسته از جاهایی که نام‌های کلاس یا رابط ظاهر می‌شوند حذف می‌شود\&. به 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 شوند (که در غیر این صورت در هر صفحه‌ای تفاوتی وجود خواهد داشت)\&. برچسب زمانی شامل شماره انتشار دستور \f3javadoc\fR است و در حال حاضر چیزی شبیه به این نمایش داده می‌شود: \f3<!-- Generated by javadoc (build 1\&.5\&.0_01) on Thu Apr 02 14:04:52 IST 2009 -->\fR\&. .TP -nocomment .br کل بدنهٔ کامنت‌ها، شامل توضیحات اصلی و تمام تگ‌ها را سرکوب کرده و فقط اعلان‌ها را تولید می‌کند\&. این گزینه به شما امکان می‌دهد از فایل‌های مبدأیی که در ابتدا برای هدف دیگری در نظر گرفته شده بودند دوباره استفاده کنید تا بتوانید در مراحل اولیهٔ یک پروژه جدید، مستندات HTML اسکلتی تولید نمایید\&. .TP -sourcetab \fItablength\fR .br تعداد فاصله‌هایی (spaces) را که هر tab در کد مبدأ استفاده می‌کند مشخص می‌سازد\&. .SH "فایل‌های آرگومان خط فرمان (COMMAND-LINE ARGUMENT FILES)" برای کوتاه کردن یا ساده‌سازی دستور \f3javadoc\fR، می‌توانید یک یا چند فایل حاوی آرگومان‌های دستور \f3javadoc\fR (به جز گزینه‌های \f3-J\fR) را مشخص کنید\&. این قابلیت به شما امکان می‌دهد دستورات \f3javadoc\fR با هر طولی را روی هر سیستم‌عاملی بسازید\&. .PP یک فایل آرگومان می‌تواند شامل گزینه‌های \f3javac\fR و نام فایل‌های مبدأ در هر ترکیبی باشد\&. آرگومان‌های درون فایل می‌توانند با فاصله (space) یا خط جدید از هم جدا شوند\&. اگر یک نام فایل شامل فاصله‌های درونی است، کل نام فایل را در علامت نقل‌قول دوتایی قرار دهید\&. .PP نام‌های فایل درون یک فایل آرگومان نسبت به دایرکتوری جاری سنجیده می‌شوند، نه نسبت به محل فایل آرگومان\&. نویسه‌های عام (\f3*\fR) در این فهرست‌ها مجاز نیستند (مانند مشخص کردن *\&.java)\&. استفاده از علامت اتساین (@) برای تفسیر بازگشتی فایل‌ها پشتیبانی نمی‌شود\&. گزینه‌های \f3-J\fR پشتیبانی نمی‌شوند زیرا آن‌ها به راه‌انداز (launcher) ارسال می‌گردند، که از فایل‌های آرگومان پشتیبانی نمی‌کند\&. .PP هنگامی که دستور \f3javadoc\fR را اجرا می‌کنید، مسیر و نام هر فایل آرگومان را با پیشوند نویسهٔ @ وارد کنید\&. وقتی دستور \f3javadoc\fR با آرگومانی مواجه می‌شود که با علامت اتساین (@) شروع شده است، محتویات آن فایل را در فهرست آرگومان‌ها جایگزین و باز می‌کند\&. .PP \f3مثال ۱: یک فایل آرگومان منفرد\fR .PP می‌توانید از یک فایل آرگومان به نام \f3argfile\fR برای نگهداری تمام آرگومان‌های دستور \f3javadoc\fR استفاده کنید: \f3javadoc @argfile\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، از رابط برنامه‌نویسی عمومی (public programmatic interface) استفاده کنید\&. این رابط در \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 به دایرکتوری والد بسته‌ای با نام کامل بروید\&. سپس دستور \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 همراه با دایرکتوری والد بالاترین سطح بسته استفاده کنید\&. نام یک یا چند بسته‌ای را که می‌خواهید مستندسازی کنید، مشخص نمایید: .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 همراه با فهرستی از مسیرها به ریشه هر درخت که با دونقطه (:) جدا شده‌اند، استفاده کنید\&. نام یک یا چند بسته‌ای را که قصد مستندسازی آن‌ها را دارید مشخص نمایید\&. نیازی نیست تمام فایل‌های منبع یک بسته مشخص زیر یک دایرکتوری ریشه واحد قرار داشته باشند، اما باید در جایی در امتداد مسیر منبع یافت شوند\&. .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 در دایرکتوری مقصد مشخص‌شده ذخیره می‌شوند\&. از آنجا که دو یا چند بسته در حال تولید هستند، سند دارای سه فریم 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\&. هیچ‌یک از گزینه‌ها نباید شامل نویسه‌های خط جدید (newline) میان علامت‌های نقل‌قول تکی باشند\&. برای مثال، اگر این نمونه را کپی و جای‌گذاری می‌کنید، نویسه‌های خط جدید را از گزینهٔ \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 جریان‌های ورودی، خروجی استاندارد و خطای استاندارد را تعیین می‌کنند\&. مقدار \f3Null\fR به ترتیب مقدار پیش‌فرض برای \f3System\&.in\fR، \f3System\&.out\fR و \f3System\&.err\fR است\&. .SS "مثال MAKEFILE (THE MAKEFILE EXAMPLE)" این یک نمونه از یک \f3makefile\fR در GNU است\&. علامت‌های نقل‌قول تکی آرگومان‌های \f3makefile\fR را احاطه می‌کنند\&. برای یک نمونه از \f3makefile\fR در Windows، بخش \f3makefiles\fR از پرسش‌های متداول Javadoc را در آدرس 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 متن سربرگ (header) را در پاورقی کپی می‌کند\&. .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 FAQ در http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137483\&.html مراجعه کنید\&. .SH "خطاها و هشدارها (ERRORS AND WARNINGS)" پیام‌های خطا و هشدار، به‌جای خط خاص درون کامنت مستندسازی، حاوی نام فایل و شماره خطِ مربوط به خط اعلان (declaration) هستند\&. .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 بازنویسی می‌شود\&. مسیر دایرکتوری‌ها را برای Windows با نقطه ویرگول (;) و برای Oracle Solaris با دونقطه (:) از هم جدا کنید\&. \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 javah(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