Java Documentation Tips and Tricks

Java documentation is important to do, but hard to love. Those little @link and @author tags are time-consuming to write but vital to improving the readability of the program.  

Fortunately, there are even extensions that can generate JavaDocs for you using AI. Read on to learn more about Javadocs best practices, JavaDocs utility options, using AI extensions to write Javadocs, and more. Read on to learn: 

What Are Javadocs?

Are Javadocs Still Used?

Javadocs were introduced in the first JDK release and have been updated in every JDK release since. Today, many IDEs allow you to use an AI assistant to generate relevant Javadocs.  

Example of Java Documentation 

1. Write the following class body public class BurgersManager { }
2. Think: “Well I should have some CRUD ops in that manager”
3. Write some: public...
4. Think “What should I return? Well void will be good for now”
5. public void addBurger(Burger burger) { // TODO implement that later } public …
6. Think: “Should I return the instance of the eaten burger or void will fit? Well, like #4 rules …”
7. public void eat(Burger burger, boolean fast) { // TODO …
8. Tell to myself: “Oh dang, coffee time. Where is my coffee …”
9. Searching, drinking, talking to colleagues
10. Then telling to myself: “Let’s get back to work. What was I doing?”

Thinking documentation before code will help you clarify your mind and lay out clearly what you need to achieve with the code. The first step could be writing the following code: 

 
/**
 * This class allows to manage burgers by providing CRUD operations using burgers and 
 * acts as a singleton. In order to get the instance of this manager, the method 
 * {@link #getInstance()} can be used. Then CRUD operations can be called like the following:
 * 

{@link #addBurger(Burger)} in order to add a burger that will be managed by the * singleton instance ;

* @author Thierry Wasylczenko * @version 0.1 * @since BurgerQueen 1.0 */ public class BurgersManager { }

This is a short example that:

• Forces you to think what is the purpose of the class you are creating
• Helps you identify your needs
• Reminds you what you are doing, even after taking your break
• Helps you estimate what still needs to be done

Why Javadocs Help Teams Collaborate

Best Practices for Using Javadocs

In Javadoc you have nine tags. Read on to learn more about these tags and the best practices for Java documentation using each tag.  

• @author
• @version
• @param
• @return
• @exception/@throws
• @see
• @since
• @serial/@serialField/@serialData
• @deprecated

Use @link and @linkplain for Pointing to Some Code

@link and @linkplain can be useful to refer to classes and methods if there is a dependency. In order to make it easier to navigate through methods and classes, you can use @link. It works like this: 

• {@link BurgersManager} to point to a class
• {@link BurgersManager burgers manager} to point to a class with a given label
• {@link #eat(Burger, boolean)} to point to a method inside the same class
• {@link #eat(Burger, boolean) eat} to point to a method inside the same class with a given label
• {@link BurgersManagers#eat(Burger, boolean)} to point to a method inside another class
• {@link BurgersManagers#eat(Burger, boolean) burgers manager eat} to point to a method inside another class with a given label

The difference between @link and @linkplain is that the latter one doesn’t produce a monospaced code font.

Use @code for Code Snippets

Often, you can find some code inside a Javadoc to illustrate how to use a method, class or to provide some other example. In order to display the code correctly and preventing some markup to be interpreted such as <String> and so on, you can use the @code.

 
{@code 
List burgers = new ArrayList<>();
  for(int index = 0; index < 10; index++) {
    burgers.add(new Burger(“Burger #” + index)); 
  }
}

The @code will generate the <pre> markup for you.

Use @value to Insert the Value of a Field in the Documentation

/**
 * The default value for this field is {@value}.
*/
public static final String BURGER_SHOP_NAME = "Thierry's shop";

But you can also refer to another constant, for example:

/**
 * The default value for this field is {@value} when the value 
 * of {@link #OWNER} is {@value #OWNER}.
 */
public static final String BURGER_SHOP_NAME = "Thierry's shop";

/**
 * The default owner of this awesome burger shop.
 */
public static final String OWNER = " Thierry";

Indicate When the Features Have Been Available With @since

It is often useful to indicate when a class or a method became available in your code. To implement this Javadoc, use the @since tag followed by the version/year since the feature or class has been implemented: 

/**
 * This awesome class is for doing awesome things
 * @since burger-core-0.1
 * @version 0.2
*/
public class BurgersManager {

  /**
   * Allows to eat burgers
   * @since burger-core-0.2
   */
  public void eat(Burger burger, boolean fast) {
    // TODO
  }
}

Don’t Be Anonymous, Use @author

For Non-Void Methods, Always Use @return

/** Get the address.
 * @return
 */
public String getAddress() { /* … */ }

Instead of having the poor Java documentation like the example above, you can easily have a better version: 

/**
 * Get the address of this burger shop. The address is of the following format:
 * {@code address line 1
 * address line 2
 * zipcode city}
 * @return the address of this burger shop or {@code null} if not filled.
 */

Clarify What Parameters Mean With @param

What is more frustrating than seeing a method that takes a parameter named something unclear, like i with no documentation? Sometimes you can guess the purpose of that parameter thanks to the method's name. Then again, sometimes you cannot. So in your documentation you should use @paramin order to indicate what this parameter means and, potentially, indicate what the valid values are. In our case, i could be the level of the log and the values will be INFO, DEBUG or TRACE. Another case where this tag is particularly useful is when the value corresponds to an index. In some case indexes start at 0 and in other at 1. @param is the right tag to describe such differences. 

Generating Javadocs

javadoc {packages|source-files} [options]

You can specify the packages, space separated, or source files, also space separated, for which you want to generate the documentation.

Here's a short description of some options javadoc utility accepts:

• -author for generating the @author tag in the generated documentation
• -d directory for generating the documentation elsewhere than in the current directory
• -nodeprecated for avoiding the generation of documentation for code marked as @deprecated
• -protected to include protected and public class and class members -private to include private class and class members
• -public to only include public class and class members

Tools such as IDEs are also able to generate your documentation but also preview it to this if it is well formatted.

Dependency management tools like Maven and Gradle also include a phase or task to generate your documentation. And this is great! Because your documentation can always be produced with the release and so it will always be up to date.

Final Thoughts

Documentation isn't the only pathway to creating efficiency in your Java development practice. By eliminating rebuilds and redeploys with JRebel, you could save a month of development time annually. See for yourself during your 14-day free trial. 

Try JRebel Free