I’ve been developing Javadocs at SAP for a few years, and have a lot of respect for Sun’s tool and the way it emphasizes documentation during all phases of the development process – documentation that always stays in synch with your code. So just in case you are looking for inspiration in the new year when documenting your Java APIs, I include my ‘top six’ favorite tips below:
- Include overview documentation:
Provide context for your whole API in the overview. Unless you assume that people coming to your API know exactly what it’s about in advance (and even if they do), an overview is key.
- Include package documentation for every package:
This is so often overlooked. Package documentation is a very visible source of information in the Javadoc package, and often the first place developers go for information. If your package documentation is missing, it’s also quite obvious. Simply drop the package.html into each package, and Javadoc will find it and ‘do the right thing.’
- Include additional supporting files:
Rely on doc-files directories to spiffy up your documentation with additional files. Embed graphics or links to additional documentation (pdfs, html files, .doc files, source code) that can be included in your rich documentation set. You simply create a subdirectory called ‘doc-files’ in any package, drop the graphic or other file into it, and include a relative link to it in your doc comments. Javadoc will automatically gather up any files in doc-files directories and include them in the build.
- Customize the stylesheet!
While we’re at it, in the Javadoc command, use ‘bottom’ for your copyright, ‘doctitle,’ ‘windowtitle,’ and ‘header’ for your API name, and stick a logo in your footer with ‘footer.’
- TEST your Javadocs:
Clean up the warnings evoked by the compiler (often a way to spot inaccuracies in your code as well), visually inspect the HTML, and use DocCheck, Sun’s utility for testing the completeness and syntax of your documentation comments. Make sure everything you expose in Javadocs has a documentation comment.
- Do it first!
Lastly, endeavor write your documentation comments before you write your code. This is a suggestion from the good book The Elements of Java Style (Vermeulen, et. al.), and it makes sense. This way, you’ve created your specification and your documentation all at once, and as long as you remember to update your comments as code changes, you’ve got a streamlined documentation process.
Have I delivered inspiration for the new year? Check out these links below for additional sources of inspiration/information:
- You might check out this example of exemplary Javadocs…
- For lots of good information from Sun, check out their information on Writing API Specifications and Writing Doc Comments.
- Finally, if you’d like extensive training, James Bisso often offers a course on Documenting APIs in Java through UC Berkeley Extension.
Here’s to comprehensive and usable API documentation in the new year; cheers!