Usually developers do not write any or they write useless documentation and most of the time it is outdated.
Javadoc
Javadoc is the API documentation on package, class, field and method level.
It should answer the question how to properly use the classes but are more like a reference
and are not so good in conveying the whole picture.
Nevertheless this is very important and easiest to keep up to date as the documentation
is embedded directly in the source code.
So what is important to document especially in javadoc documentation?
The goal is that another developer can understand what is this class for and how he can use it.
A very helpfull construct for designing OO systems but also for documenting them are CRC cards.
CRC
CRC stands for Class-Responsibility and Collaborations. Basically it works it is very simple way on how to design an OO system. You take a stack of card, each representing an object in your system. You write on the very limited space what is the responsibility of the class.
Because the space is so limited on the card it forces you to only write one responsibility for the class which is also good design principle
"Single Responsibility Principle"
- Every class should only have one responsibility.
- As a rule of thumb it should only have one reason why you would want to change something on this class
The next section is the "Collaborators":
This section answers what others classes does this class need to achieve its responsibility.
I write this class uses object xy to ...
It also states which other objects are using this object and why they depend on it.
It should have an Example:
An example says more than thousands words how to theoretically use the API. Unit tests are usually good examples that show how to use the API and it can be linked to them or the test code can be pasted as an example.
Other questions that are of interest to the developer
Is this class meant for subclassing (if not and most of the time it shouldbe final to avoid subclassing)
Thread safety
How to properly initialize and create the object (is it by a factory, when is it in a proper state?)
Package level documentation
package level document describes all classes in a certain package. Actually a package is for me a module and all classes in a package usually belong together and are coupled in some way and depend on each other. Coupling between packages should be minimized, and subpackages referencing classes from top level packages should be avoided.
Basically package level documentation also can be described in the CRC principle.
Formatting in javadoc
javadoc will become html. I use a comment {@link Class#method(int,String}
