Java Documentation Comments

Java Documentation Comments

Java supports three kinds of annotation methods. The first two are // and/ * */, the third is called the Explanatory Note, which starts with /** and ends with * /.

The description comment allows you to embed information about the program in your program. You can use the Javadoc tool software to generate information and output it to an HTML file.

Explanatory notes that make it easier for you to record your program information.

Javadoc label

The Javadoc tool software identifies the following tags:

label	Description	Example
@author	Identifies the author of a class	@author description
@deprecated	To nominate an expired class or member	@deprecated description
{@docRoot}	Indicates the path to the root directory of the current document	Directory Path
@exception	Flags an exception thrown by a class	@exception exception-name Explanation
{@inheritDoc}	Comments inherited from the immediate parent class	Inherits a comment from the immediate surperclass.
{@link}	Insert a link to another topic	{@link Name text}
{@linkplain}	Insert a link to another topic, but the link displays a plain text font	Inserts a in-line link to another topic.
@param	Describes the parameters of a method	@param parameter-name Explanation
@return	Description return value type	@return Explanation
@see	Specify a link to another topic	@see Anchor
@serial	Description of a serialization property	@serial description
@serialData	Describes data written through the WriteObject () and writeexternal () methods	@serialData description
@serialField	Describes a Objectstreamfield component	@serialField Name Type description
@since	Mark when a specific change is introduced	@since Release
@throws	The same as @exception tags.	The @throws tag has the same meaning as the @exception tag.
{@value}	Displays the value of the constant, which must be a static property.	Displays the value of a constant, which must be a static field.
@version	Specify the version of the class	@version Info

Document comments

After the beginning of the /** , the first row or lines are the main descriptions of the classes, variables, and methods.

After that, you can include one or more kinds of @ tags. Each @ tag must be at the beginning of a new line or at the beginning of a line followed by an asterisk (*).

Multiple labels of the same type should be placed in a group. For example, if you have three @see tags, you can put them together one after the other.

The following is an example of a class's description comment:

/* * * This class draws a bar chart * @author runoob * @version 1.2 */ Javadoc Output What

The Javadoc tool takes the source code of your Java program as input and outputs some HTML files that contain comments from your program.

The information for each class will be in its own HTML file. Javadoc can also output inherited tree structures and indexes.

Because the Javadoc implementation is different, the work may be different, you need to check the version of your Java development system and other details, select the appropriate Javadoc version.

Instance

The following is a simple example of using explanatory notes. Note that each comment is in front of the item it describes.

After Javadoc processing, the comments for the Squarenum class are found in the squarenum.html.

Squarenum.java File Code:

ImportJava.io.*; /*** This class demonstrates the documentation comments *@authorAyan amhed*@version1.2*/ Public classSquarenum {/*** This method returns the square of Num. * This is a multiline description.   You can use * as many lines as. * @paramnum The value to is squared. * @returnnum Squared. */    Public DoubleSquareDoublenum) {      returnNum *num; }   /*** This method is inputs a number from the user. * @returnThe value input as a double. * @exceptionIOException on input error. * @seeIOException*/    Public DoubleGetNumber ()throwsIOException {InputStreamReader ISR=NewInputStreamReader (system.in); BufferedReader InData=NewBufferedReader (ISR);      String str; STR=Indata.readline (); return(NewDouble (str)). Doublevalue (); }   /*** This method demonstrates square (). * @paramargs Unused. * @returnNothing . * @exceptionIOException on input error. * @seeIOException*/    Public Static voidMain (String args[])throwsIOException {squarenum ob=NewSquarenum (); DoubleVal; System.out.println ("Enter value to be squared:"); Val=Ob.getnumber (); Val=Ob.square (Val); System.out.println ("Squared value is" +val); }}

as follows, use the Javadoc tool to process the Squarenum.java file:

$ javadoc squarenum.javaloading source file Squarenum.java ... Constructing Javadoc information ... Standard Doclet version1.5. 0_13building Tree forAll the packages and classes ... Generating squarenum.html ... Squarenum.java:39:warning-@returntag cannot be used on method withvoid returntype. Generating Package-frame.html ... Generating Package-summary.html ... Generating Package-tree.html ... Generating constant-values.html ... Building Index forAll the packages and classes ... Generating Overview-tree.html ... Generating Index-all.html ... Generating deprecated-list.html ... Building Index forAll classes ... Generating Allclasses-frame.html ... Generating Allclasses-noframe.html ... Generating index.html ... Generating Help-doc.html ... Generating Stylesheet.css ...1warning$

Java Documentation Comments