The Javadoc Tags Explained

In the previous article, we have discussed how to write Java documentation comments and how to use Javadoc tags in documentation comments. In this article, we will discuss each Javadoc tag and finally, we will demonstrate the usage of important Javadoc tags with an example.

Learn complete Java programming language at Java Tutorial | Learn Java Programming with Examples.

What is Javadoc?

Javadoc is a tool which comes with JDK and it is used for generating Java code documentation in HTML format from Java source code, which requires documentation in a predefined format.

The Javadoc Tags

The Javadoc utility recognizes the following tags:

Document tags that begin with an “at” sign (@) are called stand-alone tags (also called block tags), and they must be used on their own line. Tags that begin with a brace, such as {@code}, are called in-line tags, and they can be used within a larger description. You may also use other, standard HTML tags in a documentation comment Let's learn more about Java code documentation comments.

Let's discuss each Javadoc in detail.

@author

The @author tag documents the author of a class or interface. It has the following syntax:

@author description

Here, description will usually be the name of the author. You will need to specify the -author option when executing Javadoc in order for the @author field to be included in the HTML documentation.

{@code}

The {@code} tag enables you to embed text, such as a snippet of code, into a comment. That text is then displayed as-is in code font, without any further processing, such as HTML rendering. 

It has the following syntax:

{@code code-snippet}

@deprecated

The @deprecated tag specifies that a program element is deprecated. It is recommended that you include @see or {@link} tags to inform the programmer about available alternatives. 

The syntax is the following:

@deprecated description

Here, description is the message that describes the deprecation. The @deprecated tag can be used in documentation for fields, methods, constructors, classes, and interfaces.

{@docRoot}

{@docRoot} specifies the path to the root directory of the current documentation.

@exception

The @exception tag describes an exception to a method. 

It has the following syntax:

@exception exception-name explanation

Here, the fully qualified name of the exception is specified by exception-name, and explanation is a string that describes how the exception can occur. The @exception tag can only be used in documentation for a method or constructor.

{@inheritDoc}

This tag inherits a comment from the immediate superclass.

{@link}

The {@link} tag provides an in-line link to additional information. 

It has the following syntax:

{@link pkg.class#member text}

Here, pkg.class#member specifies the name of a class or method to which a link is added, and text is the string that is displayed.

{@linkplain}

Inserts an in-line link to another topic. The link is displayed in a plain-text font. Otherwise, it is similar to {@link}.

{@literal}

The {@literal} tag enables you to embed text into a comment. That text is then displayed as-is, without any further processing, such as HTML rendering. 

It has the following syntax:

{@literal description}

Here, description is the text that is embedded.

@param

The @param tag documents a parameter. It has the following syntax:

@param parameter-name explanation

Here, parameter-name specifies the name of a parameter. The meaning of that parameter is described by explanation. The @param tag can be used only in the documentation for a method or constructor, or a generic class or interface.

@return

The @return tag describes the return value of a method. 

It has the following syntax:

@return explanation

Here, explanation describes the type and meaning of the value returned by a method. The @return tag can be used only in the documentation for a method.

@see

The @see tag provides a reference to additional information. Two commonly used forms are shown here:

@see anchor
@see pkg.class#member text

In the first form, an anchor is a link to an absolute or relative URL. In the second form, pkg.class#member specifies the name of the item, and text is the text displayed for that item.

@serial

The @serial tag defines the comment for a default serializable field. 

It has the following syntax:

@serial description

Here, description is the comment for that field.

@serialData

The @serialData tag documents the data written by the writeObject( ) and writeExternal( ) methods. 

It has the following syntax:

@serialData description

Here, description is the comment for that data.

@serialField

For a class that implements Serializable, the @serialField tag provides comments for an ObjectStreamField component. 

It has the following syntax:

@serialField name type description

Here, name is the name of the field, a type is its type, and description is the comment for that field.

@since

The @since tag states that an element was introduced in a specific release. 

It has the following syntax:

@since release

Here, release is a string that designates the release or version in which this feature became available.

@throws

The @throws tag has the same meaning as the @exception tag.

{@value}

{@value} has two forms. The first displays the value of the constant that it precedes, which must be a static field. 

It has this form:

{@value}

The second form displays the value of a specified static field. 

It has this form:

{@value pkg.class#field}

Here, pkg.class#field specifies the name of the static field.

@version

The @version tag specifies the version of a class or interface. 

It has the following syntax:

@version info

Here, info is a string that contains version information, typically a version number, such as 2.2. You will need to specify the -version option when executing Javadoc in order for the @version field to be included in the HTML documentation.

Documentation Comments Example

Following the program uses few of the important tags available for documentation comments. You can make use of other tags based on your requirements. After being processed by Javadoc, the documentation about a SquareNum class will be found in SquareNum.html.

/**
 * This class demonstrates documentation comments.
 * 
 * @author Ramesh Fadatare
 * @version 1.8
 */
public class SquareNum {
    /**
     * This method returns the square of num. This is a multiline description. You
     * can use as many lines as you like.
     * 
     * @param num The value to be squared.
     * @return num squared.
     */
    public double square(double num) {
        return num * num;
    }

    /**
     * This method inputs a number from the user.
     * 
     * @return The value input as a double.
     * @exception IOException On input error.
     * @see IOException
     */
    public double getNumber() throws IOException {
        // create a BufferedReader using System.in
        InputStreamReader isr = new InputStreamReader(System.in);
        BufferedReader inData = new BufferedReader(isr);
        String str;
        str = inData.readLine();
        return (new Double(str)).doubleValue();
    }

    /**
     * This method demonstrates square().
     * 
     * @param args Unused.
     * @exception IOException On input error.
     * @see IOException
     */
    public static void main(String args[]) throws IOException {
        SquareNum ob = new SquareNum();
        double val;
        System.out.println("Enter value to be squared: ");
        val = ob.getNumber();
        val = ob.square(val);
        System.out.println("Squared value is " + val);
    }
}

Output:

Enter value to be squared: 
2
Squared value is 4.0

How to generate Javadoc and more examples are at Using Java Documentation Comments.

Learn complete Java programming language at Java Tutorial | Learn Java Programming with Examples.

References

Using Java Documentation Comments