Documentation Comment In Java

Published by Admin on 13/05/202013/05/2020

What is Documentation Comment In Java?

1. The JDK contains a very useful tool called javadoc, that generates HTML documentation from java source file. Documentation comment in Java is more important, because we can understand the program.
2. If a user will add comments that start with a special delimiter \** & ending with */ then user can easily produce professional looking documentation.

a) Comment Insertion

i) The Javadoc utility extract information about the following

• Packages
• Public classes & Interfaces
• Public & Protected methods
• Public & Protected fields

ii) A user can supply comments for each of these features. A documentation comment start with /** & end with */. Each documentation comment contains free from text followed by tags. A tags starts with @ such as
@author
@version & so on.
iii) The first sentence of the free from test should be a summery statement. The javadoc utility automatically generates summery pages that extracts these sentence. In the free from text, the user can use HTML tags such as
<em>…..</em> For emphasis,
<code>……..</code> For a monospaced type
Writer Font <strong>….</strong> For strong & <img src>……tag to include an image.
Do not use heading <h1>…. upto <h6> or <hr>

b) Class comment

i) This must be placed after any import statements, directly before class definition. A class comment might look like

/** Summery
free - from - text
<code> - - </code>
<em>- - - </em>
<img src> - - -
<strong>- - -</strong>
*/
For Ex. 
/**
A <code> card </code> object represents a playing card, such as "Queen of Hearts". A card has a suit
(Diamond Heart, Heart, Spade Or Club) & a value
(1=Ace,2-------10,11=Jack,12=Queen,13=King)
-*/
public class Card{
}

c) Method comments

Each method comment must immediately precede the method that is describe. In addition to the general purpose tag user can the following tags.

@param variable name description – This tag adds an entry to the “parameters’ section of the current method. The description can contains multilines & can use HTML tags. All @param tags for a method must be kept together.

@return description– This tag adds an entry to the “returns” section. The description can span multiple lines & can use HTML tags.

@throws class description– This tag adds a note that this method may throw an exception. The documentation comment looks like

/**  Summary
free - from - text
@param variable name description
@return description
@throws class description
*/
For Ex.
/**
Raise the salary of an employee
@param byPercent The percentage by which to raise the salary(eg 10=10%)
@retunr the almost of the raise
*/
public double raiseSalary(double byPercent){
   double raise=salary*byPercent/100;
   - - - - -
}

d) Field comments

A user only need to document public fields- generally that means static constant.

For eg.
 /**
     The "Hearts" card suit
*/
public static final int HEARTS=1;

e) General comments

The following tags can be used in class documentation comment in java

i) @author name
This tag makes an author entry multiple @author tags can be given one for each author.
ii) @version text
This tag makes version entry . The text can be any description of the current version
for eg. @version 1.6.9 12/11/2014
iii) @since text
This tag makes a since entry the text can be any description of the version that introduced this features.
for eg. @since version 1.6.1
iv) @deprecated text
This tag adds a comments that the class, method or a variable should no longer to user
v) @deprecated use text
Use this tag for suggesting a replacement for a deprecated class, method or a variable
for eg. @deprecated use <code> set visible</code> instead.
vi) @see reference
This tag adds a hyperlink in the “see also” section. It can be used with both classes & reference. Reference can be one of the following

• <a href=”—–“> label </a>
• “text”
• packageName.className#Feature label

The third syntax for reference is mostly used.
For eg.
@see java.util.Scanner #next next
The see tag using the 1st syntax is as follow
@see <a href=”corejava.html”>The Core Java Home Page</a>
If @see tag is followed by a double quote character then the text is displayed in see also section
@see “Core Java & Vol II “
vii) @link tag
A user can placed hyperlinks to other classes or methods any where in any of the comments. Insert a sepecial tag of the form
{@link package.class#features label}

Questions :-

1. What is Java documentation comments?
2. What is Java documentation example?
3. What is class comments?
4. What is Method comments?
5. What is Field comments?
6. What is General comments?
7. How do you write a good comment in code?
8. What is single line comment in Java?
9. How do you declare a comment in Java?
10. What are the three types of comments in Java?