Document your Java code automatically with Javadoc

If you do any type of programming, you know that one of the most tedious tasks is documenting your code. Whether you find it mildly boring or a business you face with absolute fear, code documentation is essential. Others need to understand how your code works, and you might even be one of them if you read it later!

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

Javadoc can help you document your code automatically

I hope you are already following good coding practices and including explanatory comments in your code. While this kind of in-code commenting is certainly helpful, it doesn’t provide anything like a textbook.

Of course, another programmer can step through your code and read the specific classes, methods, and functions in front of them. It is, however, extremely difficult to get a good overview of all the code or to find functions that might be useful when you don’t know they exist. Javadoc aims to solve this problem.

Javadoc will automatically generate a detailed, user-friendly HTML manual for all of your code. Even better, it does this by using comments from code you’re probably already writing.

What exactly is Javadoc and how does it work?

Javadoc is a standalone program that comes with Oracle’s Java Development Kit (JDK) releases. In fact, you cannot download it separately. When you download and install one of Oracle’s JDK versions, it also installs Javadoc.

USE VIDEO OF THE DAY

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

In a nutshell, Javadoc allows you to write your code and its documentation at the same time. It simplifies your workflow and lets you use your time more efficiently.

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 some strings in your comments. These let Javadoc know what you want to include in the final documentation.


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

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

In 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 get used to the format and available tags, writing such comments is a piece of cake.

Here is an example to illustrate simple Javadoc comments describing a function that gets an image from a URL and displays it on the screen. The comment immediately precedes the function and describes what it does. This comment block also uses three section-specific tags: @param, @come backand @see.



* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute @link}">{@link URL}. The name
* argument is a specifier that is relative to the url argument.
*


* 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 above code, it generates a web page similar to the following:

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

The @tags used at the end of the comment generate the Settings, Returnand See also sections you see.

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

The @come back The tag documents the value returned by the function, if any. It can be a simple one-word description or several 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 simply called Image. Note that references made with this tag are clickable links, allowing a reader to directly access the referenced element in the final HTML code.

Other tags are available, such as @version, @author, @exception and others. When used correctly, tags help link items together and allow easy navigation of documentation.

Run Javadoc on your source code

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

javadoc 

To see exactly what Javadoc can do in more detail, check out the official documentation for 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

Above is a list of files and directories created by Javadoc. As you can see, there are quite a few. For this reason, you must ensure that you are not in the same directory as your source code when running the program. It could create quite a mess.

To view your newly created documents, simply open the index.html file in your favorite browser. You will get a page like this:

This is the documentation of a single, short Java class to illustrate the output. The header indicates the name of the class as well as the methods it contains. Scrolling down reveals more detailed definitions of each of the class methods.

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

Javadoc can help you keep your Java code and all relevant documentation organized and easy to use. Whether you’re doing it for your future forgetful 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.


8 Best Java Programming Blogs

The 8 Best Java Blogs for Programmers

Read more


Comments are closed.