...
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:
...
The idea is to provide useful information, or at least to not waste the reader’s time with useless information.
<TODO: place them here>
...