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.

What Is JavaDoc

This tool uses the “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. The 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 a Doc comment in Java is similar to a 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 them.

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 normal text. As a convention, the same tags are placed together.

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

#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.

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 for 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 documentation. Follow the below steps to generate the documentation using IntelliJIdea.

• Click Tools -> Generate JavaDoc

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

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:

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

• 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 the contents of this file is shown below.

• Similarly, given below is 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

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 the 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 the source code.

=> Visit Here To Learn Java From Scratch.