Basic Javadoc Guide

Introduction

This article tries to summarize the basics of Javadoc: Importance, basic usage and tags reference to create documentation for the existing two types: Usage documentation and Implementation documentation.

Background

The Usage documentation is aimed at users that need to understand the functionality of a code and how to use it on their own code, but they really don't need to know how the implementation works. Let's use any API as an example, to use it on your code, you just need to know what needs to be sent and what is returned, how the code does the job is not really necessary in this case.

The Implementation documentation aims for the user that needs detailed descriptions on how the functionality is implemented on each method, it very useful for those who maintain, enhance or debug the code.

Is it important to use both types of documentation? The answer is a big solid YES. It is one of the best practices you should be implementing on your code. When you create code, nobody except you knows what it does and how it should be used, if someone needs your code, it will not be so easy to understand it quickly and let's say that you need that code 3 months later, probably you will not remember it. Additionally, using Javadoc, you can generate external documentation, very useful as a public reference.

Using the Code

What should have documentation?

Well, everything can have documentation, but for least there are 3 areas where the documentation is required (it doesn't matter if they're public, protected or private):

• Classes
• Constants, Variables
• Methods

Here is a reference of the code, syntax and tags to do basic documentation.

Special Characters

First of all, in your documentation, you should escape special characters that have special meaning in HTML, for example &, < and >, in this case:

• Change & to &amp;
• Change < to &lt;
• Change > to &gt;

Other special characters that need escape are:

• &reg; (®)
• &Aacute; (Á)
• &aacute; (á)
• &ntilde; (ñ)

Remember there are a lot of these characters, you can use this table as a reference for the rest of them. Notice that Javadoc is like writing a HTML, you can use tags like <a href>, <p>, <br> and others.

Javadoc Tags

There are tags for several purposes, here are some of them and where to use them:

@author

Use this tag to describe the author.

Applies to: Classes, Interfaces and Enums

Example:

/**
 * @author diego
 */
public class MyLittleClass{...}  

Taking advantage of HTML tags, you can use something more elaborated like:

/**
 * @author diegohp (Diego Hernandez Perez) - 
 * <a href="mailto:hp.diego@gmail.com">hp.diego@gmail.com</a>
 */
public class MyLittleClass{...} 

@version

Use it to provide the version of the software.

Applies to: Classes, Interfaces and Enums

Examples:

/**
 * @version 1.0
 */
public class MyLittleClass{...}   

/** 
 * @author 5.4.2
 */
public class MyLittleClass{...}  

@since

Use it to describe the first appearance of a functionality.

Applies to: Classes, Interfaces, Enums, fields and methods.

Examples:

/**
 * @since 1.0
 */
public class MyLittleClass{...}   

/**
 * @since 4.3.2
 */
public class MyLittleClass{...}  

@see

Use it to make reference of other elements of documentation.

Applies to: Classes, Interfaces, Enums, fields and methods.

Examples:

Referencing a class or interface:

/**
 * @see ArrayList
 */
public class MyLittleClass{...}   

Referencing a method of a class or interface (also use # to access variables of the class and YourClass#yourMethodOrField to reference the method/field of other classes)

/**
 * @see #add(java.lang.Object) 
 */
public void addUsingExtraSteps(Object object, int i){...} 

@param

Use it to describe a parameter of a method.

Applies to: Methods.

Example:

/**
 * @param file       The file that needs to be renamed.
 * @param newName    The the new name of the file.
 */
public void renameFile(File file, String newName){...}  

@return

Use it to describe a return value.

Applies to: Methods.

Example:

/**
 * @return   A string with the password encrypted.
 */
public String encrypt(String password){...} 

@throws or @exception

Use it to describe an exception that may be thrown by the current method.

Applies to: Methods.

/** 
 * @throws FileNotFoundException   If the files doesn't exist.
 */
public File getFile(String path) throws FileNotFoundException {…} 

@deprecated

Use it to describe a class, field or method as outdated.

Applies to: Classes, Interfaces, Enums, fields and methods.

Examples:

/**
 * @deprecated Use {@link #encryptWithMD5(String)} instead.
 */
public String encrypt(String password){...} 

/**
 * @deprecated Use {@link MyNewLittleClass} instead because blablabla.
 */
public class MyLittleClass{...} 

{@inheritDoc}

Use it when you want to copy the description from the overridden method.

Applies to: Overriding Methods.

/**
 * {@inheritDoc}
 */
@Override
public String encrypt(String password){...} 

{@link}

Use it when you want to link to other symbols (class, method, field). Remember that using # shows you the methods of fields of a class.

Applies to: Classes, Interfaces, Enums, fields and methods.

Examples:

/**
 * This class is similar to {@link MyLittleClass} but the {@link #myNewLittleMethod(int, int)} 
 * is faster than {@link MyLittleClass#myNewLittleMethod(int, int)}
 */
public class MyNewLittleClass{...} 

{@value #STATIC_FIELD}

Use it to print the value of a static variable (constants).

Applies to: Classes, Interfaces, Enums, fields and methods, but only making reference of a static field.

/**
 * This class makes a lot of calculations based on the magic number 
 * that is {@value #MY_MAGIC_NUMBER}
 */
public class MyLittleClass{...}   

Points of Interest

Something I notice everyday is that most of the times, the names of classes and methods are very clear on what they do, BUT it is not an excuse for not doing its documentation!

Also, do not extend the content of the documentation too much, especially for the Implementation one, otherwise the code becomes hard to read.

History

• 24^th September, 2013: Created the article