...

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/

...

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.

...