10
3) Java Documentation Comment
Documentation comments are commonly utilized when developing large programs or software applications, as they facilitate the creation of API documentation. This documentation serves as a reference, providing information about the classes, methods, arguments, and other elements used in the code.
To generate the documentation API, the javadoc tool is employed. Documentation comments are enclosed between /** and */. These comments are specifically formatted to capture relevant details about the code, including class descriptions, method explanations, parameter information, and return values.
Syntax:
Tag |
Syntax |
Description |
{@docRoot} |
{@docRoot} |
Represents the relative path to the root directory of the generated document from any page. |
@author |
{@author name – text} |
Indicates the author of the class. |
@code |
{@code text} |
Displays the text in code font without interpreting it as HTML markup or nested Javadoc tags. |
@version |
{@version version-text} |
Specifies the “Version” subheading and includes the version text when the -version option is used. |
@since |
{@since release} |
Adds a “Since” heading with the specified release text to the generated documentation. |
@param |
{@param parameter-name description} |
Adds a parameter with the given name and description to the “Parameters” section. |
@return |
{@return description} |
Required for every method that returns a value (except void), describing the return value. |
Let’s use the javadoc tag in a Java program.
Calculate.java
import java.io.*;
/**
* <h2> Calculation of numbers </h2>
* This program implements an application
* to perform operation such as addition of numbers
* and print the result
* <p>
* <b>Note:</b> Comments make the code readable and
* easy to understand.
*
* @author Anurati
* @version 16.0
* @since 2021-07-06
*/
public class Calculate{
/**
* This method calculates the summation of two integers.
* @param input1 This is the first parameter to sum() method
* @param input2 This is the second parameter to the sum() method.
* @return int This returns the addition of input1 and input2
*/
public int sum(int input1, int input2){
return input1 + input2;
}
/**
* This is the main method uses of sum() method.
* @param args Unused
* @see IOException
*/
public static void main(String[] args) {
Calculate obj = new Calculate();
int result = obj.sum(40, 20);
System.out.println("Addition of numbers: " + result);
}
}
Compile it by javac tool:
Create Document
Create documentation API by javadoc tool:
After the generation process, the HTML files about the Calculate class have been successfully created within the current directory named “abcDemo”. To access the contents, simply open the HTML files in a web browser. Within these files, you will find the detailed explanation of the Calculate class as provided in the documentation comment.
Java comments are executable?
In Java, comments serve as non-executable elements that are ignored by the compiler and interpreter. However, before the lexical transformation of code during compilation, the contents of the code are encoded into ASCII format. This encoding process is performed to facilitate easier processing and handling of the code by the compiler.
Test.java