What Is JavaDoc And How To Use It To Generate Documentation

This tutorial explains what are JavaDoc tool and JavaDoc Comments and methods to generate code documentation:

JavaDoc is a special tool that is packaged with the JDK. It is used to generate the code documentation of Java source code in HTML format.

It is a documentation generator for the Java language from Sun Microsystems (presently Oracle Corporation).

=> Check ALL Java Tutorials Here.

JavaDoc tool

What Is JavaDoc

This tool uses “doc comments” format to document Java classes. IDEs like Eclipse, IntelliJIDEA, or NetBeans have an in-built JavaDoc tool to generate HTML documentation. We also have many file editors in the market that can help the programmer to produce JavaDoc sources.

Apart from source code documentation this tool also provides API that creates “doclets” and “taglets” that we use to analyze the structure of a Java application.

One point to note is that this tool does not affect the performance of the application in any way as the compiler removes all the comments during the compilation of the Java program.

Writing comments in the program and then using JavaDoc to generate the documentation is to help the programmer/user understand the code.

The HTML documentation generated by JavaDoc is API documentation. It parses the declarations and generates a set of source files. Source file describes fields, methods, constructors, and classes.

Note that before we use the JavaDoc tool on our source code, we must include special JavaDoc comments in the program.

Let’s now move on to comments.

JavaDoc Comments

Java language supports the following types of comments.

#1) Single line comments: The single-line comment is denoted by “//” and when the compiler encounters these, it ignores everything that follows these comments till the end of the line.

#2) Multiline comments: Multiline comments are represented using “/*….*/”. So on encountering the ‘/*’ sequence, the compiler ignores everything that follows this sequence till it encounters the closing sequence ‘*/’.

#3) Documentation comments: These are called Doc comments and they are used by the tool to generate API documentation. The doc comments are indicated as “/** documentation */”. As we can see, these comments are different from the normal comments described above. The doc comments may also contain HTML tags inside them as we will see shortly.

So to generate API documentation using this tool, we must provide these documentation comments (doc comments) in our program.

Structure Of A JavaDoc Comment

The structure of Doc comment in Java is similar to multiline comment except that the doc comment has an extra asterisk (*) in the opening tag. So the doc comment starts with ‘/**’ instead of ‘/*’.

Additionally, JavaDoc style comments can also have HTML tags inside it.

JavaDoc Comment Format

Based on the programming construct on which we want to document, we can place doc comments above any construct like class, method, field, etc. Let’s go through examples of each of the constructs’ doc comments.

Class Level Format

The doc comment format at a class level will look as shown below:

/**
* Mechanic
* 
* Please see the {@link sth.javadoctutes.Person} class for true identity
* @author SoftwareTestingHelp
* 
*/
public class Mechanic extends Person {
    // fields and methods
}

As shown above, a class-level doc comment will have all the details including the author of the class, links if any, etc.

Method Level Format

Given below is an example of a doc format at the method level.

/**
 * <p> simple method description …
* <a href="http://www.softwaretestinghelp.com">JavaDoc!</a>
 * </p>
 * @param msg the message to be printed
 * @return void 
 * @see <a href=" http://www.softwaretestinghelp.com ">JavaDoc</a>
 * @since 2.0
 */
public void printMessage (String msg) {
    // do things
    return 0;
}

As we can see from the above example, we can have any number of tags in the doc comment of the method. We can also have paragraphs inside the comment description indicated by <p>…</p>.

We also have special tags to describe the return value (@return) and parameters of the method (@param).

Field Level Format

The following example shows the doc comment for a field.

/**

* The public name of a message

*/

private String msg_txt;

As seen from the above example, we can also have plain comments without any tags. Note that JavaDoc does not generate any documentation for private fields unless we specify a private option with the JavaDoc command.

Now let’s discuss the tags that are used with the doc comments.

JavaDoc Tags

Java provides various tags that we can include in the doc comment. When we use these tags, the tool parses these tags to generate a well-formatted API from the source code.

Each tag is case-sensitive and starts with a ‘@’ sign. Each tag starts at the beginning of the line as we can see from the above examples. Otherwise, the compiler treats it as a normal text. As a convention, the same tags are placed together.

There are two types of tags that we can use in doc comment.

#1) Block Tags: Block tags have the form of @tag_name.

Block tags can be placed in the tag section and follow the main description.

#2) Inline Tags: Inline tags are enclosed in curly braces and are of the form, {@tag_name}. The inline tags can be placed anywhere inside the doc comment.

The following table lists all the tags that can be used in the doc comments.

TagDescriptionApplies to
@author xyz Indicates the author of class, interface, or enum.Class, Interface, Enum
{@docRoot} This tag has the relative path to the document’s root directory. Class, Interface, Enum, Field, Method
@version version Specifies software version entry. Class, Interface, Enum
@since since-text Specifies since when this functionality exists Class, Interface, Enum, Field, Method
@see referenceSpecifies references (links) to other documentationClass, Interface, Enum, Field, Method
@param name description Used to describe the method parameter/argument. Method
@return description Provides return value description. Method
@exception classname descriptionSpecifies exception that method may throw in its code. Method
@throws classname description
@deprecated description Specifies if the method is outdatedClass, Interface, Enum, Field, Method
{@inheritDoc} Used to copy the description from the overridden method in case of inheritance Overriding Method
{@link reference} Provides references or links to other symbols. Class, Interface, Enum, Field, Method
{@linkplain reference} Same as {@link} but is displayed in plain text. Class, Interface, Enum, Field, Method
{@value #STATIC_FIELD} Describe the value of a static field.Static Field
{@code literal} Used to format the literal text in code font similar to {@literal}. Class, Interface, Enum, Field, Method
{@literal literal} Indicates literal text. the enclosed text is interpreted literally without any style formatting.Class, Interface, Enum, Field, Method
{@serial literal} Description of a serializable field. Field
{@serialData literal} Documents the data written by the writeExternal( ) or writeObject( ) methods. Field, Method
{@serialField literal} Describes an ObjectStreamField component. Field

Generate Java Doc

To create a JavaDoc you do not need to compile the Java file. We can generate JavaDoc documentation in two ways.

#1) Using JavaDoc Command Via Command Line

The command-line tool allows us to run the command through it.

This command can be executed on a command line and has the following syntax.

user@sth:~$javadoc –d doc src\*

In the above command, we assume that all the files and Java classes are in the src folder. Also, the documentation will be generated in the specified ‘doc’ directory.

Note that running the “javadoc” command without any parameters or flags results in an error.

#2) Using The Tool From Any Of The Java IDEs.

All the major Java IDEs provide built-in functionality of generating documentation using the JavaDoc tool.

Using this built-in functionality is easier and also recommended than using a command-line tool to generate Java documentation.

Using JavaDoc With IntelliJIdea

Let’s generate documentation for a simple program using IntelliJIdea IDE.

We will consider the following program for which we have provided doc comments.

/**
 * Main class
 *
 * Please see the {@link www.softwaretestinghelp.com} class for true identity
 * @author SoftwareTestingHelp
 *
 */
public  class Main{
    /**
     * <p> main method description …
     * <a href="http://www.softwaretestinghelp.com">JavaDoc!</a>
     * </p>
     * @param args[] string array
     * @return void
     * @see <a href=" http://www.softwaretestinghelp.com ">JavaDoc</a>
     *
     */
    public static void main(String args[]) {
        System.out.println("Hello,World!!");
    }
}

We know that we need not compile the program or project to generate JavaDoc. IntelliJIdea Ide provides a built-in tool to generate the documentation. Follow the below steps to generate the documentation using IntelliJIdea.

  • Click Tools -> Generate JavaDoc

Generate JavaDoc

  • The following screen is opened when the JavaDoc tool is clicked.

JavaDoc tool opened

Here we can specify whether we want to generate documentation for the whole project or only one class etc. We can also specify the output directory where the documentation files will be generated. There are various other specifications as shown in the above figure.

Click OK once all the parameters are specified.

  • Now we can see the Java Doc generation process in the output window. A sample Java Doc output window looks as shown below:

JavaDoc output window

  • Once the generation completes, the following files are generated.

JavaDoc generation

  • As we specified the Main class, the file Main.html is generated. Note that the index.html also has the same contents as Main.html.
  • The file help-doc.html contains general definitions of Java entities. A sample of contents of this file is shown below.

API Documents Organized

  • Similarly, given below is a sample content in the file Main.html

a sample content in the file Main.html

Thus, this is the way in which we can generate documentation using this tool in IntelliJ idea. We can follow similar steps in other Java IDEs like Eclipse and/or NetBeans.

Frequently Asked Questions

Q #1) What is the use of JavaDoc?

Answer: JavaDoc tool comes with JDK. It is used to generate the code documentation for Java source code in HTML format. This tool requires that the comments in the source code are provided in a predefined format as /**….*/. These are also called doc comments.

Q #2) What is the Java documentation example?

Answer: Java Doc documentation tool generates HTML files so that we can view the documentation from the web browser. The real live example of JavaDoc documentation is the documentation for Java libraries at Oracle Corporation, http://download.oracle.com/javase/6/docs/api/.

Q #3) Do private methods need JavaDoc?

Answer: No. Private Fields and methods are only for developers. There is no logic in providing documentation for private methods or fields which are not accessible to end-user. Java Doc also does not generate documentation for private entities.

Q #4) What is JavaDoc Command?

Answer: This command parses the declarations and doc comments in Java source files and generates corresponding HTML documentation pages containing documentation for public and protected classes, nested classes, constructors, methods, fields, and interfaces.

However, JavaDoc does not generate documentation for private entities and anonymous inner classes.

Conclusion

This tutorial described the JavaDoc tool packaged with JDK that is useful for generating the code documentation for Java source code in HTML format. We can generate documentation by either executing the Java Doc command via command tool or by using the in-built JavaDoc functionality available in most of the Java IDEs.

We saw how we can use the tool with IntelliJIdea Java IDE to generate documentation. The tutorial also explained various tags that can be used with doc comments so that the tool can generate user-friendly documentation detailing all the information related to source code.

=> Visit Here To Learn Java From Scratch.