...

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.

...

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.

...

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.

Outside 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

...