Additional Blogs by SAP
cancel
Showing results for 
Search instead for 
Did you mean: 
moyalynne
Active Contributor
0 Kudos
If you're a Java developer, you know all about Sun's Javadoc documentation utility, which automatically generates HTML-based Java API documentation from declarations and signatures in your source code. You know that you can additionally expand upon this documentation by writing comprehensive and complete documentation comments in your code, and you do this religiously (right?). And by the way, you also enhance your Javadocs with package- and overview-level documentation, and you even customize your output with a stylesheet. No?

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:

  1. 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.
  2. 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.'
  3. 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.
  4. 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.'
  5. 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.
  6. 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: Here's to comprehensive and usable API documentation in the new year; cheers!

-m