GOAL: Enable developers to be successful when using our APIs.

It sounds simple, but it’s harder than you might think. People read and interpret APIs differently. We should strive to remove as much ambiguity from ours as possible. 

Standards

Thoroughness: The Javadoc should provide enough information for the user to be able to succeed in their task. But not more. A longer description can cause reader confusion.

Consistency: The Javadoc should be consistent in format and content. The user should feel at home when using different parts of the API because the information provided is consistent across different parts of the API.

Usability: The Javadoc should be easy to find/search and use.

Approachability: The documentation should make the API seem approachable. The customer should feel confident that they can get their job done via the API with the help of the Javadoc.

Guidelines

All Classes, Constants, and public Methods* should have useful Javadoc comments.

* Some methods are very simple/self-explanatory. For the very simplest of methods (like some set and get methods) we can skip the Javadoc comment.

Javadoc comments should include:

• Any side-effects of the method
• @param tags for each parameter, even if the content is trivial
• @returns tag for the return value, even if trivial
• What type of object will be contained in any returned collection
• What happens if any of the arguments supplied to the method are null
• Whether the method ever returns null, or if not, what it returns if there is no value
• @throws tags for all declared exceptions, describing the circumstances they are thrown
• @throws tags for any likely undeclared exceptions
• A @since tag for any interface, or interface method
• @see tags for other classes or methods that interact with the thing being documented in interesting ways, or for other ways to get the same information

Short and to the point is better. Do not include "This method" or "This class", etc. in the description:

Great: "Returns a NodeID."

Not great: "This method returns a NodeID"

Deprecation

Include the version at which the item was deprecated so it's easier to track and eventually remove from the API.

Examples

Atlassian/Jira does a good job of creating concise, helpful Javadoc: https://docs.atlassian.com/software/jira/docs/api/7.6.0/

Avoiding Repetition/Redundancy

In general, you want to avoid things like this, where the doc doesn’t really do anything but explain what’s obvious and already contained in the class name:

/**

* Implementation of OurInterface.

*/

public class OurInterfaceImplementation implements OurInterface { ... }

Get/Set methods are often good examples of documenting the obvious:

/**

* @return Returns the xyz.

*/

public String getXyz() {

return xyz;

}

/**

* @param xyz

*         The xyz to set.

*/

public void setXyz(String xyz) {

this.xyz = xyz;

}

The idea is to provide useful information, or at least to not waste the reader’s time with useless information.

Some Good Examples

<TODO: place them here>

Resources

• Atlassian’s Javadoc standards: https://developer.atlassian.com/server/confluence/javadoc-standards/
• Sun's long piece on javadoc comments: https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html