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.
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.
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:
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"
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:
Get/Set methods are often good examples of documenting the obvious:
The idea is to provide useful information, or at least to not waste the reader’s time with useless information.
<TODO: place them here>