doc

1. doc Presented by: Mohamad amin rastgoo Be a hacker

2. What is the need? • writing code isn’t the only important activity—documenting it is at least as important. • you need a special comment syntax to mark the documentation, and a tool to extract those comments and put them in a useful form. • نوشتن کد تنها کار مهم نیست داکیومنت کردن به همان اندازه مهم است • شما به یک شکل خاص کامنت برای مشخص کردن این داکیومنت ها و یک وسیله برای استخراج این کد ها و قرار دادن آنها به یک فرم مشخص نیاز دارید Be a hacker

3. solution • Java has done this: • JAVADOC It is distributed as part of the Java SDK and its output stage is designed to be extensible through doclet creation • راه حل جاوا برای این کار javadoc است • این برنامه به عنوان قسمتی از java SDK منتشر میشود. Be a hacker

4. What is Javadoc? • 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. • You can use it to generate the API (Application Programming Interface) documentation or the implementation documentation for a set of source files. • ابزار Javadoc در یک برنامه جاوا تعاریف و کامنت ها را پیمایش میکند و یک مجموعه صفحات html که به صورت پیش فرض کلاسهای public و protected را و کلاسهای nested )نه هر کلاس داخلی ) و interface connstructor و متد ها و فیلدها را در بردارد تولید میکند. • شما میتوانید از آن برای تولید documentationApi ( رابط برنامه نویسی برنامه) و یا implementation documnet برای یک مجموعه سورس کد استفاده کنید. Be a hacker

5. 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, or pass in an explicit list of package names. • When documenting individual source files, you pass in a list of source (.java) filenames. • شما میتوانید ابزار JAVADOC را بر روی کل مجموعه یا سورس کدهای خاص و یا هر دو انجام دهید .زمانی که تمام بسته را document میکنید همچنین میتوانید از -subpackage برای پیمایش بازگشتی از بالا به پایین استفاده کنید یا یک لیست مشخص از بسته ها را استفاده کنید. • زمانی که سورس کدهای خاص را داکیومنت میکنید لیستی از فایلهای .java را میدهید Be a hacker

6. How to use Javadoc? • A doc comment consists of the characters between the characters /** that begin the comment and the characters */ that end it. • Leading asterisks are allowed on each line. The text in a comment can continue onto multiple lines. • یک doc comment از حروف /** که کامنت را آغاز میکند و حروف /* که آن را پایان میدهد تشکیل شده است. • علامت های ستاره در هر خط مجاز هستند و متن درون یک کامنت میتواند در چندین خط ادامه یابد Be a hacker

7. Example on a doc comment /**This seminar * is provided * to introduce * JavaDoc */ Be a hacker

8. Document comments placement • Documentation comments are recognized only when placed immediately before class, interface, constructor, method, or field declarations • Documentation comments placed in the body of a method are ignored. Only one documentation comment per declaration statement is recognized by the Javadoc tool. • Document comments تنها در صورتي تشخيص داده ميشوند كه بلافاصله قبل از كلاس ،interface،constructor، method يا تعريف فيلد باشند • Document comment هايي كه ر بدنه يك متد قرار دارند ناديده گرفته ميشوند. تنها يك document method براي هر قسمت تعريف توسط ابزار avadoc شناخته ميشود Be a hacker

9. Document comments tags • قسمت tag از اولين بلاك تگ شروع ميشود،كه توسط اولين @ كه خط را شروع ميكند تعريف ميشود(ستاره ها و جاهاي خالي و جداكننده هاي /** را ناديده ميگيرد).ممكن است كه يك قسمت tag بدون هيچ توضيح اصلي داشت.ولي توضيح اصلي نميتواند پس از يك قسمت تگ ادامه پيدا كند. • 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 Be a hacker

10. Document comments tags • يك tag يك keyword ويژه در doc commentاست كه javadoc ميتواند پردازش كند.دو نوع تگ وجود دارد:block tags كه به صورت @tag ديده ميشوند(به عنوان تگ هاي standalone نيز شناخته ميشوند و تگ هاي in-line كه در آكولاد قرار ميگيرند {@tag} • A tag is a special keyword within a doc comment that the Javadoc tool can process. There are two kinds of tags: block tags, which appear as @tag (also known as "standalone tags"), and in-line tags, which appear within curly braces, as {@tag} /** @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */ Be a hacker

11. 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 in a single statement, but this statement can have only one documentation comment, which is copied for all fields • كامنت ها به صورت html نوشته ميشوند. • ستاره ها در هر خط ناديده گرفته ميشوند. • خط اول هر كامنت بايد يك خلاصه از كل كامنت باشد. • جاوا اجازه ميدهد كه فيلد هاي مختلف را در يك جمله تعريف كنيم ولي اين جمله تنها ميتواند يك داكيومنتيشن داشته باشد كه براي همه كپي ميشود. Be a hacker

12. 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 your source code. The tags start with an "at" sign (@) and are case-sensitive • A tag must start at the beginning of a line or it is treated as normal text. • ابزار javadoc تگ هاي ويژه را زماني كه در يك كامنت جاوا جاي داده شده باشند پيمايش ميكند. • اين تگ ها به شما اجازه ميدهند كه به طور اتوماتيك يك Api كامل و زيبا از سورس كد خود ايجاد كنيد.تگ ها با يك @ شروع ميشوند و case sensitive هستند. • تگ ها بايد در اول خط شروع شوند يا به عنوان يك متن معمولي با آنها رفتار ميشود. Be a hacker

13. Tags • @author • {@docRoot} • @deprecated • @exception • {@inheritDoc} • {@link} • {@linkplain} • @param • @return • @see • @serial • @serialData • @serialField • @since • @throws • {@value} • @version Be a hacker

14. Tags • @authorname-text Adds an "Author" entry with the specified name-text to the generated docs when the -author option is used • @deprecateddeprecated-text Adds a comment indicating that this API should no longer be used (even though it may continue to work) • {@docRoot} Represents the relative path to the generated document's (destination) root directory from any generated page. • @exceptionclass-namedescription The @exception tag is a synonym for @throws. Be a hacker

15. {@inheritDoc} • {@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. • 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 Be a hacker

16. Tags • {@link  package.class#memberlabel} Inserts an in-line link with visible text label that points to the documentation for the specified package, class or member name of a referenced class. • {@linkplain  package.class#memberlabel} Identical to {@link}, except the link's label is displayed in plain text than code font. Useful when the label is plain text • @paramparameter-namedescription Adds a parameter to the "Parameters" section. The description may be continued on the next line. This tag is valid only in a doc comment for a method or constructor. • @returndescription 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. Be a hacker

17. @see • @seereference 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. • @seepackage.class#memberlabel • Adds a link, with visible text label, that points to the documentation for the specified name in the Java Language that is referenced. Be a hacker

18. Tags • @serialfield-description | include | exclude • Used in the doc comment for a default serializable field. • @serialFieldfield-namefield-typefield-description • Documents an ObjectStreamField component of a Serializable class's serialPersistentFields member • @serialDatadata-description • The data-description documents the types and order of data in the serialized form. • @sincesince-text • Adds a "Since" heading with the specified since-text to the generated documentation. Be a hacker

19. Tags • @throwsclass-namedescription • The @throws and @exception tags are synonyms. Adds a "Throws" subheading to the generated documentation, with the class-name and description text. The class-name is the name of the exception that may be thrown by the method. • {@value} • When used in the doc comment of a static field, displays the value of the constant. • @version  version-text • Adds a "Version" subheading with the specified version-text to the generated docs when the -version option is used. This tag is intended to hold the current version number of the software that this code is part of Be a hacker

20. Where Tags Can Be Used ? • these tags can be used in all doc comments: @see, @since, @deprecated, {@link}, {@linkplain}, and {@docroot}. • Tags kinds: • Overview Documentation Tags • Package Documentation Tags • Class and Interface Documentation Tags • Field Documentation Tags • Constructor and Method Documentation Tags Be a hacker

21. Overview Documentation Tags Be a hacker

22. Package Documentation Tags Be a hacker

23. Class and Interface Tags Be a hacker

24. Field Documentation Tags Be a hacker

25. Constructor and Method Documentation Tags Be a hacker

26. Refrences: • http://www.javaworld.com • http://java.sun.com Be a hacker