Java Doc

صفحه 1:
& do Java 0 Presented by: Mohamad amin rastgoo 

صفحه 2:
What is the need? java ۲7 نوشتن کد تنها کار مهم نیست ‎writing code isn’t the‏ © ‎ose‏ کردن به همان اندازه ‎only important activity‏ مهم است —documenting it is at 5 cs 7 least as important. ‏شما به یک شکل خاص کامنت‎ ۲ برای مشخص کردن این داکیومنت ها و یک وسیله برای استخراج ‎you need a special‏ 5 این کد ها و قرار دادن آنها به یک ‎comment syntax to‏ فرم مشخص نیاز دارید ‎mark the‏ documentation, and a tool to extract those comments and put them in a useful form. Bea ) CaS ae 

صفحه 3:
2 راه حل جاوا براى اين كار 6 است ل اين برنامه به عنوان قسمتى ‎SDK 5!‏ 31/3[ منتشر ميشود. solution 5 Java has done this: DJAVADOC It is distributed as part of the Java SDK and its output stage is designed to be extensible through doclet creation 

صفحه 4:
ابزار 3۷300[ در یک برنامه جاوا تعاریف و کامنت ها را پیمایش میکند و یک مجموعه صفحات |۱۳ که به صورت پیش فرض کلاسهای ااتالا0 و 0 را و کلاسهای 8560 )نه هر كلاس داخلى ) و ‎interface‏ ‏۲ و متد ها و فیلدها را در بردارد تولید میکند. شما ميتوانيد از أن برای تولید 45) documentation Api برنامه نویسی برنامه) و یا ‎implementation documnet‏ برای یک مجموعه سورس کد استفاده ‎aS‏ Bea ) CaS ae What is Javadoc? java ۵ The Javadoc tool parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages describing (by default) the public and protected classes, nested classes (but not anonymous inner classes), interfaces, constructors, methods, and fields. 5 You can use it to generate the API (Application Programming interface) documentation or the implementation documentation for a set of source files. 

صفحه 5:
0 شما میتوانید ابزار ۵/۸۲06[ را بر روی کل مجموعه یا سورس کدهای خاص و یا هر دو انجام دهيد .زمانى که تمام بسته را 006۱1۲06۱1 میکنید همچنین میتوانید از ‎subpackage-‏ برای پیمایش ‏از بالا به يايين استفاده كنيد يا 0 ها رد استفاده كنيد. ‎ao‏ زمانى كه سورس كدهاى خاص را داکیومنت میکنید لیستی از فایلهای .9۷| را میدهید ‎ ‎Bea ‎) CaS ae ‎Javadoc ‎© You can run the Javadoc tool on entire packages, individual source files, or both. When documenting entire packages, you can either use ‎-subpackages for ‎traversing recursively down from a top-level ‎directory. 0 ass in an explicit list of package names. ‎| ۱۷۷۱۵۴۱ ‏امع مطناع ول‎ individual source files, you pass in a list of source (.java) filenames. ‎ 

صفحه 6:
How to use Javadoc? java | A doc comment Gs 5! doc comment ‏يكى‎ 2 consists of the ‏که کامنت را آغاز میکند و‎ 7 characters between ‏ف /* که آن را بایان میدهد‎ the characters /** that ‏ات‎ ee begin the comment ‏بل شدو اییت.‎ 7" علامت های ستاره در هر خط مجاز /* ‎and the characters‏ هستند و متن درون یک کامنت ‎that end it.‏ میتواند در چندین خط ادامه یابد ‎Leading asterisks are‏ 5 allowed on each line. The text ina comment can continue onto multiple lines. Bea ) CaS ae 

صفحه 7:
3 Example on a doc commeéiava This seminar * is provided * to introduce * JavaDoc #7 

صفحه 8:
o a Java Document comments ‏تنها در صورتيتشخیص‌دادم‎ ‏میشوند که باهاصله قبل‌از کاس‎ (2 ۵ ait il, method ‏باشند‎ Document comment ‏هيي‌که ر بدنه يك‌متد قرار‎ ‏دارند نادیدم گرفته میشوند. تنها‎ document methods. ‏قسمتقعريفقوسط‎ psd ‏لبزار 2۷006 شناخته میشود‎ Bea ) CaS ae Document comments placement 5 Documentation comments are recognized only when placed immediately before class, interface, constructor, method, or field declarations 5 Documentation comments placed in the body of a method are ignored. Only one documentation comment per declaration statement is recognized by the Javadoc tool. 

صفحه 9:
3 Document comments tag java ۲7 قسمت و29] از اولین بلاك تگ شروع میشود.که توسط اولین © كه خط را شروع میکند تعریف میشود(ستاره ها و جاهاي خالي و جداکننده هاي /** را نادیده میگیرد).ممکن است که يك قسمت ‎tag‏ بدون هیچ توضیح اصلي داشت.ولي توضیح اصلي نمیتواند يس از يك قسمت تگ ادامه پیدا کند. Bea ) CaS ae © The tag section starts with the first block tag, which is defined by the first @ character that begins a line (ignoring leading asterisks, white space, and leading separator /**). It is possible to have a comment with only a tag section and no main description. The main description cannot continue after the tag section begins 

صفحه 10:
& Document comments tag java 5 A too isa special ‏يك وج] يك 6۷۷/0۲۵ ویژه در‎ ۲ keyword within a doc 4S culdoc comment comment that the NG FRIIS GN ss | Jewadoc tool can process. ‏ی وا یی لو‎ here are two kinds of OC Kon sae tags: block tags, which oan tag@ Sy se 44S tags appear as @tag (also ‏ميشوند(به عنوان تك هاي‎ known as "standalone ‏نیز شناخته میشوند‎ 53۳0010۳6 tags"), and in-line tags, و تگ هاي 0-1[06] که در آکولاد ‎which appear within curly‏ braces, as {@tag} )1390( ‏قرار میگیرند‎ px @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int, int) } 1 Bea ) CaS ae 

صفحه 11:
۳۲۱۱ ‏کامنت ها به صورت‎ O ‏نوشته میشوند.‎ 7 ستاره ها در هر خط نادیده گرفته میشوند. ۲7 خط اول هر كامنت بايد يك خلاصه از کل کامنت باشد. تا جاوا اجازه میدهد که فیلد هاي مختلف را در يك جمله تعریف کنیم ولي این جمله تنها میتواند يك داکیومنتیشن داشته باشد که براي همه كيي ميشود. Bea ) CaS ae rules | Comments are written in HTML © Leading asterisks: leading asterisk (*) characters on each line are discarded © The first sentence of each doc comment should be a summary sentence © Declaration with multiple fields :Java allows declaring multiple fields ina sing le statement, but this statement can have only one documentation comment, which is copied for all fields 

صفحه 12:
۲ ابزار »2۷300 تگ هاي ویژه را زماني که در يك کامنت جاوا جاي داده شده باشند پیمایش میکند. 5 اين تك ها به شما اجازه ميدهند كه به طور اتوماتيك يك ز۸0 کامل و زیبا از سورس کد خود ایجاد کنید.تگ ها با يك ۵ شروع میشوند و 856 560516 هستند. 0 تگ ها باید در اول خط شروع شوند يا به عنوان يك متن معمولي با آنها رفتار میشود. Bea ) CaS ae Java doc tags The Javadoc tool parses special tags when they are embedded within a Java doc comment. © These doc tags enable you to autogenerate a complete, well- formatted API from ‘our source code. The ‘ags start with an "at" sign (@) and are case- sensitive © Atag must start at the beginning of a line or it is treated as normal text. 

صفحه 13:
Bea ) CaS ae @author {@docRoot} @deprecated @depri @exception_ {@inheritDoc} @link} @version 

صفحه 14:
Java O {@docRoot} Represents the relative path to the generated document's (destination) root directory from any generated page. O @exception class- name description The @exception tag is a synonym for @throws. Bea ) CaS ae Tags © @author name-text Adds an "Author" entry with the specified name-text to the generated docs when the -author option is used @deprecated deprecatead-text Adds a comment indicating that this API should no longer be used (even though it may continue to work) 

صفحه 15:
{@inheritDoc} java O {@inheritDoc} Inherits (copies) documentation from the " nearest" inheritable class or implementable interface into the current doc comment at this tag's location. This allows you to write more general comments higher up the inheritance tree, and to write around the copied text. 5 This tag is valid only in these places in a doc comment: ® In the main description block of a method = In the text arguments of the @return, @param and @throws tags of a method Bea ) CaS ae 

صفحه 16:
9 @param parameter- name description Adds a parameter to the "Parameters" section. The description may be continued on the next line. This tag is valid only ina doc comment for a method or constructor. 9 @return description Adds a "Returns" section with the description text. This text should describe the return type and permissible range of values. This tag is valid only in a doc comment for a method. Bea ) CaS ae Tags ۲ package.class# member label} Inserts an in-line link with visible text /abe/ that points to the documentation for the specified package, class or member nonce ofa referenced class. O {@linkplain package.class# member label} Identical to {@link}, except the link's label is displayed in plain text than code font. Useful when the label is plain text 

صفحه 17:
&, @see java 5 @see reference Adds a "See Also" heading with a link or text entry that points to reference. = @see "string" © Adds a text entry for string. No link is generated ™ @see <a href="URL#value">label</a> © Adds a link as defined by URL#value. The URL#value is a relative or absolute URL. = @see package.class# member label © Adds a link, with visible text /abe/, that points to the documentation for the specified name in the Java Language that is referenced. Bea ) CaS ae 

صفحه 18:
Java © @serialData data- description = The data-description documents the types and order of data in the serialized form. 5 @since since-text = Adds a "Since" heading with the specified since-text to the generated documentation. Bea ) CaS ae Tags 2 @serial field-description | include | exclude = Used in the doc comment for a default serializable field. O @serialField fie/d- name field-type field- description = Documents an ObjectStreamField component of a Serializable class's serialPersistentFields member 

صفحه 19:
Tags java © @throws class-name jescription 5 {@value} = The @throws and © When used in the doc @exception tags are comment of a static synonyms. Adds a field, displays the "Throws" subheading value of the constant. to the generated 5 @version version-text documentation, with * Adds a "Version" the class-name and subheading with the description text. The specified version-text class-name is the to the generated docs name of the when the version exception that may ۳ res RP the Be Drawn oy ie current version number of the software that this code is part of Bea ) CaS ae 

صفحه 20:
<, Where Tags Can Be Usecixg © these tags can be used in all doc comments: Qsee, since, @deprecated, {@link}, {@linkplain}, and {@docroot}. © Tags kinds: [Overview Documentation Tags OPackage Documentation Tags SClass and Interface Documentation Tags OField Documentation Tags Constructor and Method Documentation Tags Bea ) CaS ae 

صفحه 21:
Overview Documentatior % Tags java Overvew Tae @see @since @author @version {@link} {@linkplain} |f@docRoott | Bea 

صفحه 22:
Package Documentation % Tags java ‎Top‏ ما۳ ‎@see ‎@since ‎@serial ‎@author ‎@version ‎{@link} ‎{@linkplain} ‎|{@docRoott i Bea ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ 

صفحه 23:
= Class and Interface Tags iava @serial @author @version {@link} {@linkplain} {@docRoot} Be a 

صفحه 24:
& Field Documentation Taciava Pell Dace @see @sinc 2 @deprecated @serial @serialField {@link} {@linkplain} {@docRoot} [{@value} ___ ‏ل‎ 

صفحه 25:
Constructor and Method ۳ Documentation Tags java 0 ۰ @see @since @deprecated @param @return @throws and @exception @serialData {@link} {@linkplain} {@inheritDoc} [{@docRoot} ‏ال‎ Bea 

صفحه 26:
3 =o Refrences: java 5 http://www.javaworld.com 5 http://java.sun.com