slide1 l.
Download
Skip this Video
Loading SlideShow in 5 Seconds..
doc PowerPoint Presentation
Download Presentation
doc

Loading in 2 Seconds...

play fullscreen
1 / 26

doc - PowerPoint PPT Presentation


  • 295 Views
  • Uploaded on

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.

loader
I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
capcha
Download Presentation

PowerPoint Slideshow about 'doc' - paul


An Image/Link below is provided (as is) to download presentation

Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.


- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -
Presentation Transcript
slide1

doc

Presented by:

Mohamad amin rastgoo

Be a hacker

what is the need
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
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
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

javadoc
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
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
Example on a doc comment

/**This seminar

* is provided

* to introduce

* JavaDoc

*/

Be a hacker

document comments placement
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

document comments tags
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 tags10
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
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
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

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

Be a hacker

slide14
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

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

slide16
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

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

slide18
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

slide19
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

where tags can be used
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

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

Be a hacker