Doc Presented by: Mohamad amin rastgoo Be a hacker.

doc

Presented by:

Mohamad amin rastgoo

Be a hacker

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

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

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 و

تولید بردارد در را فیلدها و ها متدمیکند.

تولید برای آن از میتوانید شماdocumentation Api ( رابط

) یا و برنامه نویسی برنامهimplementation documnet

کد سورس مجموعه یک برای. کنید استفاده

Be a hacker

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

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

Example on a doc comment

/**This seminar * is provided* to introduce* JavaDoc*/

Be a hacker

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،construcكالسtor ، method فيلد تعريف يا

باشندDocument comment

قرار متد يك بدنه ر كه هايي . ميشوند گرفته ناديده دارند

يك documentتنهاmethod قسمت هر براي

ابزار توسط avadocتعريفميشود شناخته

Be a hacker

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

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

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

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

Tags @author {@docRoot} @deprecated @exception {@inheritDoc} {@link} {@linkplain} @param @return @see @serial @serialData @serialField @since @throws {@value} @version

Be a hacker

Tags @author name-text

Adds an "Author" entry with the specified name-text to the generated docs when the -author option is used

@deprecated deprecated-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.

@exception class-name description

The @exception tag is a synonym for @throws.

Be a hacker

{@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

Tags {@link

package.class#member label}

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#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

@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 in a doc comment for a method or constructor.

@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.

Be a hacker

@see @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 label, that points to the documentation for the specified name in the Java Language that is referenced.

Be a hacker

Tags @serial field-

description | include | exclude Used in the doc

comment for a default serializable field.

@serialField field-name field-type field-description Documents an

ObjectStreamField component of a Serializable class's serialPersistentFields member

@serialData data-description The data-description

documents the types and order of data in the serialized form.

@since since-text Adds a "Since"

heading with the specified since-text to the generated documentation.

Be a hacker

Tags @throws class-name

description 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

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

Overview Documentation Tags

Overview Tags

@see

@since

@author

@version

{@link}

{@linkplain}

{@docRoot} Be a hacker

Package Documentation Tags

Package Tags

@see

@since

@serial

@author

@version

{@link}

{@linkplain}


Class and Interface Tags

Class/Interface Tags

@see

@since

@deprecated

@serial

@author

@version

{@link}

{@linkplain}


Field Documentation Tags

Field Tags

@see

@since @deprecated

@serial

@serialField

{@link}

{@linkplain}

{@docRoot}

{@value} Be a hacker

Constructor and Method Documentation Tags

Method/Constructor Tags

@see

@since

@deprecated

@param

@return

@throws and @exception

@serialData

{@link}

{@linkplain}

{@inheritDoc}


Refrences: http://www.javaworld.com http://java.sun.com

Be a hacker