Structure JavaDoc of Packages
| | /** |
| » | * This package called logistics contains classes for logistics. |
| | * The inventory class in this package can stock up from the cargo ship and |
| | * dispose of any contaminated supplies. |
| | * Classes of this package: |
| | * - Inventory |
| | * - Supply |
| | * - Hull |
| | * - CargoShip |
| | * - SupplyCrate |
| | * |
| » | * @author A. Lien, H. Uman |
| | * @version 1.8 |
| | * @since 1.7 |
| | */ |
| | package logistics; |
JavaDoc[26] is the documentation facility for APIs in Java. You use it to document anything that’s public in your code, including packages. If you’re writing an API and you want others to use it, that’s a must.
Here we have the JavaDoc of the logistics package.[27] At first glance, the JavaDoc comment above looks good, doesn’t it? It starts with a nice short summary sentence followed by more details and a list of all the classes in the package. It even uses special annotations to mark the @author, the @version of the current release, and the version @since when this package was added. But at second and third glance, we can spot a lot of issues here!
The summary sentence is basically superfluous. We might write that if we got paid for the number of words, and not for their quality.
The rest of the description is really too abstract. How would we actually use the classes in the package? And is a list of all the classes really needed? No, it’s not! JavaDoc generates this automatically anyway.
Last, the annotations aren’t really useful either. They duplicate information that’s in the version control system anyway. Who will keep this in sync with the code? Hands up, anyone?
In summary, most of the information here is superfluous and unnecessary. Instead, you can get it from the source directly.
But what should a package JavaDoc documentation contain? Here’s what we recommend:
| | /** |
| » | * Classes for managing an inventory of supplies. |
| | * |
| » | * <p> |
| | * The core class is the {@link logistics.Inventory} that lets you |
| | * <ul> |
| | * <li> stock it up from a {@link logistics.CargoShip}, |
| | * <li> dispose of any contaminated {@link logistics.Supply}, |
| | * <li> and search for any {@link logistics.Supply} by name. |
| | * </ul> |
| | * |
| » | * <p> |
| | * The classes let you unload supplies and immediately dispose of any supply |
| | * that was contaminated. |
| | * <pre> |
| | * Inventory inventory = new Inventory(); |
| | * inventory.stockUp(cargoShip.unload()); |
| | * inventory.disposeContaminatedSupplies(); |
| | * inventory.getContaminatedSupplies().isEmpty(); // true |
| | * </pre> |
| | */ |
| | package logistics; |
There are three parts here, separated by vertical space, and no more superfluous information.
The introductory sentence provides a (very) short summary of what you can achieve with the classes in this package.
The second part describes what you can get done with the most important classes in this package. This gives you the starting point for looking deeper into the package and also a pretty good idea whether you need it. And by using the @link annotation, you can simply click on the class and jump directly to it—the JavaDoc tool even checks that linked classes exist when it generates the documentation.
Instead of annotations like @author, which capture information that is in the version control system anyway, we provide a concrete example of how to implement the most important use case in the third part. That’s something a developer can use instantaneously.
A good package documentation can really make a difference in understandability. It lowers the entry barrier to all classes in the package. Make sure your API’s well documented, and chances are you’ll get more stars on Github!