Introduction to Javadoc

Documentation provides insights on how to use software and its features. Good documentation leads to easier adaptation of the software. Java provides a tool called Javadoc which can generate documentation in an HTML page format.

In this tutorial, we will learn how to create and use Javadoc.

Java Comments

Comments are a way of explaining what our code does. They added to the source code itself. In Java, we have three types of comments.

• Single-Line Comments(Start with // and spans an entire line)
• Multi-Line Comments(Start with /* and end with */)
• Javadoc Comments(Start with /** and end with */)

These comments are completely ignored by the compiler and do not affect the performance of our code. The Javadoc comments are used by the Javadoc tool to generate documentation for our code. It is important to write good Javadoc comments to create easy-to-read documentation.

Javadoc Comments

As discussed above, Javadoc comments help the Javadoc Tool to generate better documentation. A Javadoc comment contains two parts. It contains the description of the code and Javadoc tags for specific meta-data. These comments are placed before the class, the field, or the method that we want to add information to.

Javadoc Tags

Javadoc tags are used to specify some metadata about a piece of code. They begin with the @ symbol. There are a lot of tags defined for different purposes. Some of the most commonly used tags are explained below.

• @author is used to describe the author's name.
• @param provides information about the parameters passed to a method.
• @see is used to add a reference to some other element of the code.
• @version is used to set the version for the code.
• @return is used to describe the return value for a method.
• @exception is used to specify the type of exception if the method uses the throws keyword. The @throws can also be used.
• @deprecated is used to give a reason the part of the code was deprecated.

We can also create custom tags according to our needs. Use the following Javadoc command to create custom tags.

javadoc -tag <tag-name>:<location:allowed>:<text-name-in-output> <class-location>

Since the Javadoc tool generates an HTML page for the documentation, we can add HTML tags to our Javadoc comments to better format the description.

/**
*    <h1>Method to Print Hello World<h1>
*    <p> This method uses the <b>System.out.print()</b> method to print Hello World 
*    to the console.</p>
*/
public static void printHelloWorld()
{
    System.out.print("\n\nHello World\n\n");
}

Javadoc Comments at Class Level

Let's create a Student class and add Javadoc comments to it. We will include a brief description of the class. We will also add the @author tag to set the author name for the class and the @version tag to specify the version of the class.

/**
 * The Student class gives basic student information like student's name, and 
 * the marks scored in different subjects.
 * 
 * @author 	Justin
 * @version 1.0
 *
 */
public class Student
{
    ...
}

Javadoc Comments at Field Level

Next, we will add a few properties to the Student class and write Javadoc comments for them. We will add a simple description for each field.

public class Student
{
	/**
	 * Student name field of String type
	 */
	String studentName;
	
	/**
	 * Marks scored in Mathematics
	 */
	Double mathMarks;
	
	/**
	 * Marks scored in Science
	 */	
	Double scienceMarks;
	
	/**
	 * Marks scored in English
	 */
	Double englishMarks;
}

Javadoc Comments at Method Level

We will create a new class and add a method to this class. This method calculates the student's percentage. Let's view the Javadoc comments for this method.

/**
	 * Calculates and returns the Student's percentage based on the marks in three subjects
	 * 
	 * @param student The Student class Object
	 * @return Double type percentage based on the student's marks
	 * @throws Exception throws exception if something goes wrong
	 *
*/
public static Double calculatePercentage(Student student) throws Exception
{
	Double math = student.getMathMarks();
	Double sci = student.getScienceMarks();
	Double eng = student.getEnglishMarks();
	return (math + sci + eng) / 300;
}

Generating Javadoc

We can easily generate the Javadoc documentation page by using the following Javadoc command from the command line.

We need to specify the class or the package for which we want the documentation. Use the -d flag to specify the location where you want to create the documentation files.

javadoc -d doc <class or package name>

IDEs can also generate Javadoc documentation.

We can view the generated documentation by opening the index.html file. The following images show the generated documentation.

Summary of the classes present in the package

Student Class

The calculatePercentage() method in the JavaDocDemo Class

Summary

Javadoc is a documentation generator tool. We need to use Javadoc comments in our source code to create descriptive and easy-to-understand documentation. Javadoc provides us inbuilt tags which we can use to specify certain properties about our code. We can also create custom Javadoc tags to fulfill our requirements.