You are on page 1of 26

do

c
Presented by:

Mohamad amin rastgoo

Be a
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
solution
 Java has done this: ‫ راه حل جاوا برای این کار‬
 JAVADOC ‫ است‬javadoc
It is distributed as part ‫ این برنامه به عنوان قسمتی‬
of the Java SDK and ‫ منتشر‬java SDK ‫از‬
its output stage is
.‫میشود‬
designed to be
extensible through
doclet creation

Be a
What is Javadoc?
 The Javadoc tool parses the ‫ در یک برنامه جاوا‬Javadoc ‫ابزار‬ 
declarations and ‫تعاریف و کامنت ها را پیمایش میکند و‬
documentation comments in ‫ که به‬html ‫یک مجموعه صفحات‬
a set of Java source files and ‫ و‬public ‫صورت پیش فرض کلسهای‬
produces a corresponding set
of HTML pages describing (by nested ‫ را و کلسهای‬protected
default) the public and interface ‫(نه هر کلس داخلی ( و‬
protected classes, nested ‫ و متد ها و فیلدها را‬connstructor
classes (but not anonymous .‫در بردارد تولید میکند‬
inner classes), interfaces, ‫شما میتوانید از آن برای تولید‬ 
constructors, methods, and
fields. ‫ ) رابط‬documentation Api
‫برنامه نویسی برنامه( و یا‬
 You can use it to generate
the API (Application implementation documnet
Programming Interface) ‫برای یک مجموعه سورس کد استفاده‬
documentation or the .‫کنید‬
implementation
documentation for a set of
source files.

Be a
Javadoc
 You can run the Javadoc
tool on entire packages, ‫ را‬JAVADOC ‫شما میتوانید ابزار‬ 
individual source files, or ‫بر روی کل مجموعه یا سورس کدهای‬
both. When ‫زمانی‬. ‫خاص و یا هر دو انجام دهید‬
documenting entire ‫ میکنید‬document ‫که تمام بسته را‬
packages, you can either ‫همچنین میتوانید از‬
use
-subpackages for ‫بازگشتی از بال به پایین استفاده کنید یا‬
traversing recursively ‫یک لیست مشخص از بسته ها را‬
down from a top-level .‫استفاده کنید‬
directory, or pass in an ‫زمانی که سورس کدهای خاص را‬ 
explicit list of package ‫داکیومنت میکنید لیستی از فایلهای‬
names. ‫ را میدهید‬java.
 When documenting
individual source files,
you pass in a list of
source (.java) filenames.

Be a
How to use Javadoc?
 A doc comment ‫ از حروف‬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.

Be a
Example on a doc comment

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

Be a
Document comments
placement
 Documentation comments
are recognized only when Document comments 
placed immediately ‫تنها در صورتي تشخیص داده‬
before class, interface, ‫میشوند كه بلفاصله قبل از‬
constructor, method, or
field declarations ، ‫كلس‬
 Documentation comments interface،constructor،
placed in the body of a ‫ یا تعریف فیلد باشند‬method
method are ignored. Only
one documentation Document comment 
comment per declaration ‫هایي كه ر بدنه یك متد قرار دارند‬
statement is recognized ‫ تنها یك‬.‫نادیده گرفته میشوند‬
by the Javadoc tool.
document method
‫براي هر قسمت تعریف توسط‬
‫ شناخته میشود‬avadoc ‫ابزار‬
Be a
Document comments tags
 The tag section starts ‫ از اولین بلك تگ‬tag ‫قسمت‬ 
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 ‫ بدون‬tag ‫است كه یك قسمت‬
comment with only a
tag section and no main ‫ولي‬.‫هیچ توضیح اصلي داشت‬
description. The main ‫توضیح اصلي نمیتواند پس از‬
description cannot .‫یك قسمت تگ ادامه پیدا كند‬
continue after the tag
section begins

Be a
Document comments tags
 A tag is a special ‫ ویژه در‬keyword ‫ یك‬tag ‫یك‬ 
keyword within a doc ‫است كه‬doc comment
comment that the ‫دو‬.‫ میتواند پردازش كند‬javadoc
Javadoc tool can process.
There are two kinds of block:‫نوع تگ وجود دارد‬
tags: block tags, which ‫ دیده‬tag@ ‫ كه به صورت‬tags
appear as @tag (also ‫میشوند)به عنوان تگ هاي‬
known as "standalone ‫ نیز شناخته میشوند‬standalone
tags"), and in-line tags,
which appear within curly ‫ كه در آكولد‬in-line ‫و تگ هاي‬
braces, as }@tag{ }tag@{ ‫قرار میگیرند‬

/**
@deprecated As of JDK 1.1, replaced by }@link #setBounds(int,int,int,int){
*/

Be a
rules
 Comments are written in
HTML
 Leading asterisks:
html ‫كامنت ها به صورت‬ 
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
‫یك داكیومنتیشن داشته باشد كه‬
.‫براي همه كپي میشود‬
Be a
Java doc tags
 The Javadoc tool
parses special tags ‫ تگ هاي ویژه را‬javadoc ‫ابزار‬ 
when they are ‫زماني كه در یك كامنت جاوا جاي‬
embedded within a .‫داده شده باشند پیمایش میكند‬
Java doc comment. ‫این تگ ها به شما اجازه میدهند كه به‬ 
 These doc tags enable ‫ كامل و زیبا‬Api ‫طور اتوماتیك یك‬
you to autogenerate a ‫تگ ها‬.‫از سورس كد خود ایجاد كنید‬
complete, well- case ‫با یك @ شروع میشوند و‬
formatted API from
your source code. The .‫ هستند‬sensitive
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.

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

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

Be a
{@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
Tags
 }@link  @param parameter-
package.class#member name description
label{
Adds a parameter to
Inserts an in-line the "Parameters" section.
link with visible text label The description may be
that points to the continued on the next
documentation for the line. This tag is valid only
specified package, class in a doc comment for a
or member name of a method or constructor.
referenced class.  @return description
 }@linkplain
package.class#member Adds a "Returns"
label{ section with the
description text. This text
Identical to }@link{, should describe the
except the link's label is return type and
displayed in plain text permissible range of
than code font. Useful values. This tag is valid
when the label is plain only in a doc comment
text for a method. Be a
@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
Tags
 @serial field-
description | include |
 @serialData data-
exclude description
 Used in the doc  The data-description
comment for a documents the types
default serializable and order of data in
field. the serialized form.
 @serialField field-  @since since-text
name field-type field-
description  Adds a "Since"
 Documents an heading with the
specified since-text
ObjectStreamField
to the generated
component of a
Serializable class's documentation.
serialPersistentFields
member
Be a
Tags
 @throws class-
name description  }@value{
 The @throws and  When used in the
@exception tags doc comment of a
are synonyms. static field, displays
the value of the
Adds a "Throws" constant.
subheading to the  @version version-text
generated  Adds a "Version"
documentation, subheading with the
with the class- specified version-text
name and to the generated
description text. docs when the
The class-name is -version option is
the name of the used. This tag is
exception that intended to hold the
may be thrown by current version
the method. number of the
software that this
code is part of

Be a
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
Constructorand Method
Documentation Tags
Be a
Overview Documentation
Tags
Overview Tags

@see
@since
@author
@version
{@link}
{@linkplain}
{@docRoot}
Be a
Package Documentation
Tags
Package Tags

@see
@since
@serial
@author
@version
{@link}
{@linkplain}
{@docRoot} Be a
Class and Interface Tags
Class/Interface Tags

@see
@since

@deprecated

@serial
@author
@version
{@link}
{@linkplain}
{@docRoot} Be a
Field Documentation Tags

Field Tags
@see
@since
@deprecated
@serial
@serialField
{@link}
{@linkplain}
{@docRoot}
{@value}
Be a
Constructor and Method
Documentation Tags
Method/Constructor Tags
@see
@since
@deprecated
@param
@return

@throws and @exception

@serialData
{@link}
{@linkplain}
{@inheritDoc}
{@docRoot} Be a
Refrences:
 http://www.javaworld.com
 http://java.sun.com

Be a