15/04/2022, 16:17 Java - Documentation Comments

Java - Documentation Comments

The Java language supports three types of comments −

Sr.No. Comment & Description

1 /* text */

The compiler ignores everything from /* to */.

2
//text

The compiler ignores everything from // to the end of the line.

3
/** documentation */

This is a documentation comment and in general its called doc comment. The JDK
javadoc tool uses doc comments when preparing automatically generated
documentation.

This chapter is all about explaining Javadoc. We will see how we can make use of Javadoc to
generate useful documentation for Java code.

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.
Following is a simple example where the lines inside /*….*/ are Java multi-line comments.
Similarly, the line which preceeds // is Java single-line comment.

Example

/**

* The HelloWorld program implements an application that

* simply displays "Hello World!" to the standard output.

* @author Zara Ali

* @version 1.0

* @since 2014-03-31

*/

public class HelloWorld {

https://www.tutorialspoint.com/java/java_documentation.htm 1/7
15/04/2022, 16:17 Java - Documentation Comments

public static void main(String[] args) {

// Prints Hello, World! on standard output.

System.out.println("Hello World!");

You can include required HTML tags inside the description part. For instance, the following
example makes use of <h1>....</h1> for heading and <p> has been used for creating paragraph
break −

Example

/**

* <h1>Hello, World!</h1>

* The HelloWorld program implements an application that

* simply displays "Hello World!" to the standard output.

* <p>

* Giving proper comments in your program makes it more

* user friendly and it is assumed as a high quality code.

* @author Zara Ali

* @version 1.0

* @since 2014-03-31

*/

public class HelloWorld {

public static void main(String[] args) {

// Prints Hello, World! on standard output.

System.out.println("Hello World!");

The javadoc Tags

The javadoc tool recognizes the following tags −

https://www.tutorialspoint.com/java/java_documentation.htm 2/7
15/04/2022, 16:17 Java - Documentation Comments

Tag Description Syntax

@author Adds the author of a class. @author name-text

{@code} Displays text in code font without interpreting the

{@code text}
text as HTML markup or nested javadoc tags.

{@docRoot} Represents the relative path to the generated

{@docRoot}
document's root directory from any generated page.

@deprecated Adds a comment indicating that this API should no @deprecated

longer be used. deprecatedtext

@exception Adds a Throws subheading to the generated

@exception class-
documentation, with the classname and description
name description
text.

{@inheritDoc} Inherits a comment from the nearest inheritable Inherits a comment

class or implementable interface. from the immediate
surperclass.

{@link} Inserts an in-line link with the visible text label that
{@link
points to the documentation for the specified
package.class#member
package, class, or member name of a referenced
label}
class.

{@linkplain} Identical to {@link}, except the link's label is {@linkplain

displayed in plain text than code font. package.class#member
label}

@param Adds a parameter with the specified parameter-

@param parameter-
name followed by the specified description to the
name description
"Parameters" section.

@return Adds a "Returns" section with the description text. @return description

@see Adds a "See Also" heading with a link or text entry

@see reference
that points to reference.

@serial Used in the doc comment for a default serializable @serial field-
field. description | include |
exclude

@serialData Documents the data written by the writeObject( ) or @serialData data-

writeExternal( ) methods. description

@serialField Documents an ObjectStreamField component. @serialField field-name

field-type field-

https://www.tutorialspoint.com/java/java_documentation.htm 3/7
15/04/2022, 16:17 Java - Documentation Comments

description

@since Adds a "Since" heading with the specified since-text

@since release
to the generated documentation.

@throws The @throws and @exception tags are synonyms. @throws class-name
description

{@value} When {@value} is used in the doc comment of a {@value

static field, it displays the value of that constant. package.class#field}

@version Adds a "Version" subheading with the specified

version-text to the generated docs when the - @version version-text
version option is used.

Example

Following program uses few of the important tags available for documentation comments. You
can make use of other tags based on your requirements.

The documentation about the AddNum class will be produced in HTML file AddNum.html but at
the same time a master file with a name index.html will also be created.

import java.io.*;

/**

* <h1>Add Two Numbers!</h1>

* The AddNum program implements an application that

* simply adds two given integer numbers and Prints

* the output on the screen.

* <p>

* <b>Note:</b> Giving proper comments in your program makes it more

* user friendly and it is assumed as a high quality code.

* @author Zara Ali

* @version 1.0

* @since 2014-03-31

*/

public class AddNum {

/**

* This method is used to add two integers. This is

* a the simplest form of a class method, just to

* show the usage of various javadoc Tags.

* @param numA This is the first paramter to addNum method

* @param numB This is the second parameter to addNum method

* @return int This returns sum of numA and numB.

*/

public int addNum(int numA, int numB) {

https://www.tutorialspoint.com/java/java_documentation.htm 4/7
15/04/2022, 16:17 Java - Documentation Comments

return numA + numB;

/**

* This is the main method which makes use of addNum method.

* @param args Unused.

* @return Nothing.

* @exception IOException On input error.

* @see IOException

*/

public static void main(String args[]) throws IOException {

AddNum obj = new AddNum();

int sum = obj.addNum(10, 20);

System.out.println("Sum of 10 and 20 is :" + sum);

Now, process the above AddNum.java file using javadoc utility as follows −

$ javadoc AddNum.java

Loading source file AddNum.java...

Constructing Javadoc information...

Standard Doclet version 1.7.0_51

Building tree for all the packages and classes...

Generating /AddNum.html...

AddNum.java:36: warning - @return tag cannot be used in method with void re

Generating /package-frame.html...
Generating /package-summary.html...

Generating /package-tree.html...

Generating /constant-values.html...

Building index for all the packages and classes...

Generating /overview-tree.html...
Generating /index-all.html...

Generating /deprecated-list.html...

Building index for all classes...

Generating /allclasses-frame.html...

Generating /allclasses-noframe.html...

Generating /index.html...

Generating /help-doc.html...

1 warning

https://www.tutorialspoint.com/java/java_documentation.htm 5/7
15/04/2022, 16:17 Java - Documentation Comments

You can check all the generated documentation here − AddNum . If you are using JDK 1.7
then javadoc does not generate a great stylesheet.css, so we suggest to download and use
standard stylesheet from https://docs.oracle.com/javase/7/docs/api/stylesheet.css

Useful Video Courses

Video

Java Date And Time Online Training

16 Lectures 2 hours
Malhar Lathkar

More Detail

Video

Java Servlet Online Training

19 Lectures 5 hours

Malhar Lathkar

More Detail

Video

JavaScript Online Training

25 Lectures 2.5 hours

Anadi Sharma

More Detail

https://www.tutorialspoint.com/java/java_documentation.htm 6/7
15/04/2022, 16:17 Java - Documentation Comments
Video

Java Online Training

126 Lectures 7 hours

Tushar Kale

More Detail

Video

Java Essential Training

119 Lectures 17.5 hours

Monica Mittal

More Detail

Video

Java Essentials Online Training

76 Lectures 7 hours
Arnab Chakraborty

More Detail

https://www.tutorialspoint.com/java/java_documentation.htm 7/7