DOCUMENTATION IN JAVA.

Java Comments

The Java comments are the statements in a program that are not executed by the compiler and
interpreter. In a program, comments are like indents one makes, they are used so that it is easier for
someone who is not familiar with the language to be able to understand the code. It will also make
the job easier for you, as a coder, to find errors in the code since you will be easily able to find the
location of the bug. Comments are ignored by the compiler while compiling a code, which makes the
job more complex in the long run when they have to go through so much code to find one line.

Why do we use comments in a code?

o Comments are used to make the program more readable by adding the details of the code.
o It makes easy to maintain the code and to find the errors easily.
o The comments can be used to provide information or explanation about the variable,
method, class, or any statement.
o It can also be used to prevent the execution of program code while testing the alternative code.

Types of Java Comments

There are three types of comments in Java.
1. Single Line Comment
2. Multi Line Comment
3. Documentation Comment

GEORGE WAINAINA 0718313173/0731919231 [email protected] Page 1

1) Java Single Line Comment

The single-line comment is used to comment only one line of the code. It is the widely used and easiest
way of commenting the statements.

Single line comments starts with two forward slashes (//). Any text in front of // is not executed by
Java.

Syntax:

//This is single line comment

CommentExample1.java

public class CommentExample1 {

public static void main(String[] args) {
int i=10; // i is a variable with value 10
System.out.println(i); //printing the variable i
}
}

Output:

10

2) Java Multi Line Comment

The multi-line comment is used to comment multiple lines of code. It can be used to explain a complex
code snippet or to comment multiple lines of code at a time (as it will be difficult to use single-line
comments there).

Multi-line comments are placed between /* and */. Any text between /* and */ is not executed by
Java.

Syntax:

/*
This
is
multi line
comment
*/

GEORGE WAINAINA 0718313173/0731919231 [email protected] Page 2

CommentExample2.java

public class CommentExample2 {

public static void main(String[] args) {
/* Let's declare and
print variable in java. */
int i=10;
System.out.println(i);
/* float j = 5.9;
float k = 4.4;
System.out.println( j + k ); */
}
}

Output:

10

3) Java Documentation Comment

Documentation comments are usually used to write large programs for a project or software
application as it helps to create documentation API. These APIs are needed for reference, i.e., which
classes, methods, arguments, etc., are used in the code.

To create documentation API, we need to use the javadoc tool. The documentation comments are
placed between /** and */.

Syntax:

/**
*
*We can use various tags to depict the parameter
*or heading or author name
*We can also use HTML tags
*
*/
Creating API Document | javadoc tool

We can create document api in java by the help of javadoc tool. In the java file, we must use the
documentation comment /**... */ to post information for the class, method, constructor, fields etc.

GEORGE WAINAINA 0718313173/0731919231 [email protected] Page 3

EXAMPLE: A simple class that contains documentation comment.

package com.abc;
/** This class is a user-defined class that contains one methods cube.*/
public class M{

/** The cube method prints cube of the given number */

public static void cube(int n){System.out.println(n*n*n);}
}

To create the document API, you need to use the javadoc tool followed by java file name. There is no
need to compile the javafile.

On the command prompt, you need to write:

javadoc M.java

to generate the document api. Now, there will be created a lot of html files. Open the index.html file
to get the information about the classes.

javadoc tags

Some of the commonly used tags in documentation comments:

Tag Syntax Description

{@docRoot} {@docRoot} to depict relative path to root directory of generated document

from any page.

@author @author name - text To add the author of the class.

@code {@code text} To show the text in code font without interpreting it as html
markup or nested javadoc tag.

@version @version version-text To specify "Version" subheading and version-text when -

version option is used.

GEORGE WAINAINA 0718313173/0731919231 [email protected] Page 4

 @since @since release To add "Since" heading with since text to generated
documentation.

@param @param parameter-name To add a parameter with given name and description to
description 'Parameters' section.

@return @return description Required for every method that returns something (except
void)

Implementation:(Javadoc tag in a Java program)

// Java program to illustrate frequently used

// Comment tags

/**
* <h1>Find average of three numbers!</h1>
* The FindAvg program implements an application that
* simply calculates average of three integers and Prints
* the output on the screen.
*
* @author Pratik Agarwal
* @version 1.0
* @since 2017-02-18
*/
public class FindAvg
{
/**
* This method is used to find average of three integers.
* @param numA This is the first parameter to findAvg method
* @param numB This is the second parameter to findAvg method
* @param numC This is the second parameter to findAvg method
* @return int This returns average of numA, numB and numC.
*/
public int findAvg(int numA, int numB, int numC)
{
return (numA + numB + numC)/3;
}

/**
* This is the main method which makes use of findAvg method.

GEORGE WAINAINA 0718313173/0731919231 [email protected] Page 5

 * @param args Unused.
* @return Nothing.
*/

public static void main(String args[])

{
FindAvg obj = new FindAvg();
int avg = obj.findAvg(10, 20, 30);

System.out.println("Average of 10, 20 and 30 is :" + avg);

}
}

Output:

Average of 10, 20 and 30 is :20

For the above code documentation can be generated by using the tool ‘javadoc’:
Javadoc can be used by running the following command in the terminal.
javadoc FindAvg.java

Writing Doc Comments

Format of a Doc Comment

A doc comment is written in HTML and must precede a class, field, constructor or method
declaration. It is made up of two parts -- a description followed by block tags. In this example, the
block tags are @param, @return, and @see.

/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute <a href="#{@link}">{@link URL}</a>. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*/

GEORGE WAINAINA 0718313173/0731919231 [email protected] Page 6

public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}

Points to Note;
• The first line contains the begin-comment delimiter ( /**).
• Starting with Javadoc 1.4, the leading asterisks are optional.
• Write the first sentence as a short summary of the method, as Javadoc automatically places
it in the method summary table (and index).
• Notice the inline tag {@link URL}, which converts to an HTML hyperlink pointing to the
documentation for the URL class. This inline tag can be used anywhere that a comment can
be written, such as in the text following block tags.
• If you have more than one paragraph in the doc comment, separate the paragraphs with
a <p> paragraph tag, as shown.
• Insert a blank comment line between the description and the list of tags, as shown.
• The first line that begins with an "@" character ends the description. There is only one
description block per doc comment; you cannot continue the description following block
tags.
• The last line contains the end-comment delimiter ( */) Note that unlike the begin-comment
delimiter, the end-comment contains only a single asterisk.

GEORGE WAINAINA 0718313173/0731919231 [email protected] Page 7