If you do any kind of programming, you’ll be well aware that one of the most tedious tasks involved is documenting your code. Whether you find it mildly annoying or an undertaking that you face with absolute dread, code documentation is essential. Others need to understand how your code works, and you might even be one of them if you're reading it at a later date!

Java conveniently provides a built-in solution to the problem: Javadoc.

Javadoc Can Help You Document Your Code Automatically

Hopefully, you already follow good coding practices and include explanatory comments in your code. While this type of in-code commenting is certainly helpful, it doesn’t really provide anything comparable to a manual.

Sure, another programmer can look through your code and read about the specific classes, methods, and functions that are in front of him. It is, however, extremely difficult to get a good overview of all of the code or find functions that could be useful when you don’t know they exist. Javadoc aims to solve that problem.

Javadoc will generate a detailed and reader-friendly HTML manual for all of your code automatically. Best of all, it does it by using code comments that you’re probably already writing.

What Exactly Is Javadoc and How Does It Work?

Javadoc is a standalone program that comes bundled with Oracle’s Java development kit (JDK) releases. In fact, you can’t download it separately. When you download and install one of Oracle’s JDK versions, it will also install Javadoc.

When you run it, Javadoc generates HTML documentation from specially formatted comments in your Java source code. This process creates more useful, readable documentation while also encouraging best practices.

In a nutshell, Javadoc makes it possible for you to write your code and its documentation at the same time. It simplifies your workflow and allows you to make more efficient use of your time.

How to Create Javadoc Compatible Comments

Javadoc works by parsing specially formatted comments in your code and converting them to HTML output. The only change you really need to make is to include certain strings in your comments. These let Javadoc know what you want to include in the final documentation.

Javadoc comments should immediately precede a class, field, constructor, or method declaration. The comment itself should:

  • Begin with the three characters /**.
  • Include an asterisk at the beginning of each new line.
  • Close with the two characters */.

Within the comments, you can include HTML in the final output and include tags that will generate links to relevant parts of your codebase. You can even use things like HTML image tags to include images in the final documentation. Once you become accustomed to the format and available tags, writing such comments is a breeze.

Here’s an example to illustrate simple Javadoc comments describing a function that gets an image from a URL and prints it to the screen. The comment immediately precedes the function and describes what it does. This comment block also makes use of three section-specific tags: @param, @return, and @see. 

        /**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute <a href="#{@link}">{@link URL}</a>. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*/
public Image getImage(URL url, String name) {
    try {
        return getImage(new URL(url, name));
    } catch (MalformedURLException e) {
        return null;
    }
}

When Javadoc processes the code above, it generates a web page similar to the following:

Javadoc example html output

A browser renders Javadoc output in much the same way it displays any HTML document. Javadoc ignores extra whitespace and linebreaks unless you use HTML tags to create that space.

Use Javadoc Tags for Special Details and References

The @tags used at the end of the comment generate the Parameters, Returns, and See Also sections that you see.

You should follow the @param tag with the name of the parameter, a space, and a description of it. In the case above, there are two parameters: url and name. Notice that both appear under the same Parameters heading in the documentation output. You can list as many parameters as are necessary for the function or method that you are describing.

The @return tag documents the value that the function returns, if at all. It can be a simple one-word description or many sentences, depending on the circumstances.

The @see tag allows you to tag other functions that are related or relevant. In this case, the @see tag refers to another function called simply Image. Note that references made with this tag are clickable links, allowing a reader to jump to the referenced item in the final HTML.

There are more tags available such as @version, @author, @exception, and others. When used properly, tags help to relate items to each other and make it possible to navigate through the documentation easily.

Running Javadoc on Your Source Code

You invoke Javadoc on the command line. You can run it on single files, entire directories, java packages, or across a list of individual files. By default, Javadoc will generate the HTML documentation files in the directory where you enter the command. To get help on the specific commands available simply enter: 

        javadoc --help

To see exactly what Javadoc can do in more detail, check out the official documentation from Oracle. To create a quick set of documentation on a single file or directory you can enter javadoc on the command line followed by a filename or wildcard. 

        javadoc ~/code/filename.java

javadoc ~/code/*.java
javadoc output files

Above is a list of the files and directories that Javadoc has created. As you can see, there are quite a few of them. For this reason, you should be sure that you are not in the same directory as your source code when you run the program. Doing so could create quite a mess.

To view your newly created docs, simply open the index.html file in your preferred browser. You will get a page like the following:

javadoc generated index top

This is the documentation for a single, short Java class to demonstrate the output. The header shows the name of the class as well as the methods included within it. Scrolling down reveals more detailed definitions of each of the class methods.

javadoc methods documentation

As you can see, for any type of Java project, especially large ones with many thousands of lines of code, this type of documentation is invaluable. It would be a challenge to learn about a large codebase by reading through its source code. Javadoc pages make this process much faster and easier to follow.

Never Go Hunting Through Code Comments Again

Javadoc can help you keep your Java code and all relevant documentation organized and easy to use. Whether you’re doing it for your forgetful future self or to make things easier for a large team, Javadoc is a powerful tool that can change the way you write and interact with your Java coding projects.