There are two kinds of document that are critical to developers when working with an SDK: reference documentation, and tutorial documentation (how to get started, core concepts, etc). Both of these are equally important to developers, but it is important to understand that they serve different purposes. In this best practice we will cover reference documentation in the form of JavaDoc, as it is more relevant to our interests as API developers.
What is JavaDoc?
JavaDoc is many things:
- It is the two-asterisk comment blocks you see in Java source code. That is, it starts with
/**and ends with*/. It should not be confused with a standard Java comment, which starts with a single-asterisk/*. - It is a tool that ships with the JDK that parses source code and looks for these two-asterisk 'JavaDoc' comments.
- It is the output of this tool, which normally takes the form of a series of HTML pages that together represent the entire API surface of a library.
JavaDoc should act as the specification of the API. Engineers responsible for writing API should consider it part of their job to ensure that a JavaDoc is complete, with class-level and method-level overviews, specifying the expected inputs, outputs, exceptional circumstances, and any other detail. Whilst this documentation acts as the specification, it is important that it does not become an overly detailed guide to the programmer, or discuss how the implementation works.
The value of JavaDoc extends beyond offering it to other developers - it can also help us. This is because JavaDoc gives us a filtered view of our SDK by only showing API that is intended for public use. If we establish a routine of regularly generating JavaDoc we can review our API for issues such as missing JavaDoc, leaking implementation classes or external dependencies, and other things that aren't what we expect.
As most Java projects are based on Maven or Gradle, generating JavaDocs for a project is typically as simple as running mvn javadoc:javadoc or gradle javadoc, respectively. Getting into the habit of generating this documentation (especially with settings configured to fail on any error or warning) on a regular basis ensures that we are always able to spot API issues early, and remind ourselves of areas of our API that need more JavaDoc content to be written.
JavaDoc tags
JavaDoc ships with a number of tags such as @link, @param, and @return, which provide more context to the JavaDoc tooling, and which therefore enables a richer experience when HTML output is generated. It is extremely useful when writing JavaDoc content to keep these in the back of your mind, to ensure that they are all used when relevant. To understand when to use each of these tags, refer to the 'Tag Comments' section of the Java Platform, Standard Edition Tools Reference documentation.
JavaDoc code snippets
In an ideal world, the effort to create high quality JavaDoc would go a step further, to also include code snippets that users can copy/paste into their own software to kick start their own development. These code snippets need not be long screeds of code - it is best if they are constrained to no more than five to ten lines of code. These code snippets can be added to the JavaDoc of the relevant class or method over time, as users start to ask questions on the API.
Fortunately, since Java 18 it is now possible to use the @snippet tag to include code snippets in JavaDoc. You can read more details about this feature in the JEP 413 specification, and a great tutorial on the javaadvent.com website. In short though, the @snippet tag allows for you to bring in code snippets from external files, and apply highlighting to them. More importantly, by having the code snippets be external Java source files, you can build the code and ensure it compiles, saving you from the embarrassment of having code snippets that don't work.