Copyright tutorialspoint.

com

Java Documentation Comments

Advertisements

Java supports three types of comments. The first two are the // and the /* */. The third type is called a documentation comment. It begins with the character sequence /** and it ends with */. Documentation comments allow you to embed information about your program into the program itself. You can then use the javadoc utility program to extract the information and put it into an HTML file. Documentation comments make it convenient to document your programs.

The javadoc Tags:

The javadoc utility recognizes the following tags: Tag @author @deprecated {@docRoot} @exception {@inheritDoc} {@link} {@linkplain} Description Identifies the author of a class. Specifies that a class or member is deprecated. Specifies the path to the root directory of the current documentation Identifies an exception thrown by a method. Inherits a comment from the immediate superclass. Inserts an in-line link to another topic. Inserts an in-line link to another topic, but the link is displayed in a plain-text font. Documents a method's parameter. Documents a method's return value. Specifies a link to another topic. Documents a default serializable field. Documents the data written by the writeObject( ) or writeExternal( ) methods Documents an ObjectStreamField component. States the release when a specific Example @author description @deprecated description Directory Path @exception exception-name explanation Inherits a comment from the immediate surperclass. {@link name text} Inserts an in-line link to another topic. @param parameter-name explanation @return explanation @see anchor @serial description @serialData description

@param @return @see @serial @serialData

@serialField

@serialField name type description

@since

change was introduced.

@since release The @throws tag has the same meaning as the @exception tag. Displays the value of a constant, which must be a static field. @version info

@throws {@value} @version

Same as @exception. Displays the value of a constant, which must be a static field. Specifies the version of a class.

Documentation Comment:
After the beginning /**, the first line or lines become the main description of your class, variable, or method. After that, you can include one or more of the various @ tags. Each @ tag must start at the beginning of a new line or follow an asterisk (*) that is at the start of a line. Multiple tags of the same type should be grouped together. For example, if you have three @see tags, put them one after the other. Here is an example of a documentation comment for a class:

/* * *Ti casdasabrcat hs ls rw a hr. *@uhrZr Ai ato aa l *@eso 12 vrin . * /

What javadoc Outputs?

The javadoc program takes as input your Java program's source file and outputs several HTML files that contain the program's documentation. Information about each class will be in its own HTML file. Java utility javadoc will also output an index and a hierarchy tree. Other HTML files can be generated. Since different implementations of javadoc may work differently, you will need to check the instructions that accompany your Java development system for details specific to your version.

Example:
Following is a sample program that uses documentation comments. Notice the way each comment immediately precedes the item that it describes. After being processed by javadoc, the documentation about the SquareNum class will be found in SquareNum.html.

ipr jv.o* mot aai.; /* * *Ti casdmntae dcmnaincmet. hs ls eosrts ouetto omns *@uhrAa Ahd ato yn me *@eso 12 vrin . * / pbi casSurNm{ ulc ls qaeu /* * *Ti mto rtrstesur o nm hs ehd eun h qae f u.

*Ti i amliiedsrpin Yucnue hs s utln ecito. o a s *a mn lnsa yulk. s ay ie s o ie *@aa nmTevlet b surd prm u h au o e qae. *@eunnmsurd rtr u qae. * / pbi dul sur(obenm { ulc obe qaedul u) rtr nm*nm eun u u; } /* * *Ti mto ipt anme fo teue. hs ehd nus ubr rm h sr *@eunTevleipta adul. rtr h au nu s obe *@xeto IEcpinO ipterr ecpin Oxeto n nu ro. *@e IEcpin se Oxeto * / pbi dul gtubr)trw IEcpin{ ulc obe eNme( hos Oxeto Ipttemedrir=nwIpttemedrSse.n; nuSraRae s e nuSraRae(ytmi) BfeeRae iDt =nwBfeeRae(s) ufrdedr naa e ufrdedrir; Srn sr tig t; sr=iDt.edie) t naaraLn(; rtr (e Dul(t).obeau(; eun nw obesr)dulVle) } /* * *Ti mto dmntae sur(. hs ehd eosrts qae) *@aa ag Uue. prm rs nsd *@eunNtig rtr ohn. *@xeto IEcpinO ipterr ecpin Oxeto n nu ro. *@e IEcpin se Oxeto * / pbi sai vi mi(tigag[)trw IEcpin ulc ttc od anSrn rs] hos Oxeto { SurNmo =nwSurNm) qaeu b e qaeu(; dul vl obe a; Sse.u.rnl(Etrvlet b surd "; ytmotpitn"ne au o e qae: ) vl=o.eNme(; a bgtubr) vl=o.qaevl; a bsur(a) Sse.u.rnl(Surdvlei "+vl; ytmotpitn"qae au s a) } }
Now process above SquareNum.java file using javadoc utility as follows:

$jvdcSurNmjv aao qaeu.aa Laigsuc fl SurNmjv.. odn ore ie qaeu.aa. Cntutn Jvdcifrain. osrcig aao nomto.. Sadr Dce vrin1501 tnad olt eso .._3 Bidn te fraltepcae adcass. ulig re o l h akgs n lse.. Gnrtn SurNmhm.. eeaig qaeu.tl. SurNmjv:9 wrig-@euntgcno b ue\ qaeu.aa3: ann rtr a ant e sd i mto wt vi rtr tp. n ehd ih od eun ye Gnrtn pcaefaehm.. eeaig akg-rm.tl. Gnrtn pcaesmayhm.. eeaig akg-umr.tl. Gnrtn pcaete.tl. eeaig akg-rehm.. Gnrtn cntn-aushm.. eeaig osatvle.tl. Bidn idxfraltepcae adcass. ulig ne o l h akgs n lse.. Gnrtn oeve-rehm.. eeaig vriwte.tl. Gnrtn idxalhm.. eeaig ne-l.tl.

Gnrtn dpeae-ithm.. eeaig erctdls.tl. Bidn idxfralcass. ulig ne o l lse.. Gnrtn allse-rm.tl. eeaig lcassfaehm.. Gnrtn allse-orm.tl. eeaig lcassnfaehm.. Gnrtn idxhm.. eeaig ne.tl. Gnrtn hl-o.tl. eeaig epdchm.. Gnrtn syehe.s.. eeaig tlsetcs. 1wrig ann $
You can check all the generated documentation here: SquareNum.

Copyright tutorialspoint.com