...
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.
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.
All Classes, Constants, and public Methods* should have useful Javadoc comments.
...
Not great: "This method returns a NodeID"
Include the version at which the item was deprecated so it's easier to track and eventually remove from the API.
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:
Code Block |
---|
/** |
...
* Implementation of OurInterface. |
...
*/ |
...
public class OurInterfaceImplementation implements OurInterface { ... } |
Get/Set methods are often good examples of documenting the obvious:
Code Block |
---|
/** |
...
* @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.
<TODO: place them here>
...