rying to understand the logic of an unfamiliar Java project can be taxing. Learning the project's code is even more difficult when there is no knowledge transfer from the developer(s) who developed it. Increasingly, this is becoming a common task for developers, which isn't necessarily bad news because it provides a great opportunity for job security. A developer becomes indispensable when he or she is the knowledge source for existing projects.
Doclets, a new addition to Java SE 6, is very handy for reviewing existing source code and mastering the logic behind it. Doclet is a starting class for defining the entry point methods of the package com.sun.javadoc. The Doclet API is an extension for Javadoc, the original Java tool that automatically creates documentation from source code files. The Doclet API provides various features for customizing documentation output and offers architectural means for embedding the crux of source code logic for new projects inside custom tags—the proper way to document logic. This enables future developers to simply review the custom tags documentation to understand the logic instead of scouring through the entire documentation.
The predecessor to Doclets—Javadoc—has been around since Java came out, but it offered developers no control over the output it generated nor did it provide customization features. Javadoc specifies a fixed set of tags that developers can use to document code logic and generates boilerplate documentation in HTML. It also requires the developer to keep all code comments up to date—an easy task to forget. If the code is missing all the Javadoc-specified tags—a common scenario because in tight development schedules documenting the code takes the lowest priority, refactoring the program requires as much time as reading the code itself.
Comparing the old with the new:
- Javadoc merely looks for tags to generate documentation; Doclets compile the source files before generating the documentation.
- Doclets stop processing if they encounter any errors at compile time; Javadoc lets you generate documentation for un-compiled code.
Another documentation tool, Classdoc, is an open source project for generating documentation for missing source files from compiled code. However, it has its own limitations:
- It is limited in displaying inner classes.
- It doesn't provide hyperlinks.
- It provides only the signatures of methods, so developers must use a decompiler to understand the code in Classdoc output.
This article introduces the main classes and methods to get started with Doclets and demonstrates its features with practical examples.