Java - Documentation

2 minute read

The JDK contains a very useful tool, called javadoc, that generates HTML documentation from your source files. If you add comments that start with the special delimiter /** to your source code, you too can easily produce professional-looking documentation.

Each comment is placed immediately above the feature it describes. A comment starts with a /** and ends with a */. Each /** . . . */ documentation comment contains free-form text followed by tags. A tag starts with an @, such as @author or @param. In the free-form text, you can use HTML modifiers such as for emphasis, ... for a monospaced “typewriter” font, for strong emphasis, and even <img …> to include an image.

Class Comments

The class comment must be placed after any import statements, directly before the class definition.

Here is an example of a class comment:

/**
* A <code>Card</code> object represents a playing card, such
* as "Queen of Hearts". A card has a suit (Diamond, Heart,
* Spade or Club) and a value (1 = Ace, 2 . . . 10, 11 = Jack,
* 12 = Queen, 13 = King)
*/
public class Card {

}

@author name

This tag makes an “author” entry. You can have multiple @author tags, one for each author.

@version text

This tag makes a “version” entry. The text can be any description of the current version.

Method Comments

Each method comment must immediately precede the method that it describes. In addition to the general-purpose tags, you can use the following tags:

@param variable description

This tag adds an entry to the “parameters” section of the current method. The description can span multiple lines and can use HTML tags. All @param tags for one method must be kept together.

@return description

This tag adds a “returns” section to the current method. The description can span multiple lines and can use HTML tags.

@throws class description

This tag adds a note that this method may throw an exception. We will see in later chapter’s what is an exception

/**
* Raises the salary of an employee.
* @param byPercent percentage by which to raise the salary (e.g. 10 = 10%)
* @return the amount of the raise
*/
public double raiseSalary(double byPercent) {
    double raise = salary * byPercent / 100;
    salary += raise;
    return raise;
}

Field Comments

You only need to document public fields—generally that means static constants.

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

Comment Extraction

Let us consider we want to now create actual html documentation.

Suppose we have a package named as javaDocTest which has a class TestDoc and now we want to create documentation and we want to keep the documents in the folder KeepDocFolder then in that case we give the following command

$ javadoc -d keepDocFolder javaDocTest

Comment-1

After this command is executed the following structure will be created

Comment-2

This folder will contain the entire document for classes and methods,

Comment-3

Now if we click on the TestDoc link it will give the details of all the methods declared in the class.

Comment-4

If you liked this article, you can buy me a coffee

Categories:

Updated:

Kumar Rohit
WRITTEN BY

Kumar Rohit

I like long drives, bike trip & good food. I have passion for coding, especially for Clean-Code.

Leave a comment