We provide some guidelines to consider when writing Javadoc comments for classes.
A class should only be responsible for one thing and this thing justifies its existence. The Javadoc comment should make clear what this responsibility is.
For domain classes it is sometimes useful to know why this name was chosen. Especially if there are many possibilities and the domain is not well understood. This will later give hints why the name was deemed suitable in the past.
If the project uses a glossary, a link to the glossary entry should be useful, too.
An UML diagram is a handy visual representation of the classes static dependencies. It is easily generated with UmlGraph.
A class should document its thread-safety. If no such documentation is given, clients of the class should deem it not thread-safe.
This documentation can be given in form of annotations. The website of the book Java Concurrency in Practice provide an interesting implementation (see javadoc) that can be included in as a dependency in Maven:
<dependency>
<groupId>net.jcip</groupId>
<artifactId>jcip-annotations</artifactId>
<version>1.0</version>
</dependency>