Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs
But alas, your inbox is flooded with messages: What do the parameters mean? What beans does the servlet put in the session, and how can I access those beans from a JavaServer Page (JSP)? What URL variants can I use to invoke the servlet? And how can I tell which JSP is going to be called to render the response? Too bad you didn't write any documentation because now, rather than sitting back and reaping the rewards of your accomplishment, you're getting carpal tunnel syndrome dealing with that email flood. Doclets to the rescue!
How can doclets help? With great wisdom, the Java team understood that developers don't like to produce documentation because writing documentation takes them away from coding. The JDK team made complete documentation much easier to produce and maintain by integrating documentation production with the routine production of commented code. They produced an elegant documentation engine, JavaDoc, which scans code for the comments that developers have always written at the beginning of each class and method. Upon completing the scan, JavaDoc outputs a set of HTML pages that present the information derived from the scanned code and comments. Further, JavaDoc looks for a special set of tags within the comments and uses them to structure the resulting documentation into important categories, such as method parameters or hyperlinks to a related method.
With the onset of Java 1.2, JavaDoc became an extensible tool. Developers could produce alternative forms of documentation
by writing a
Doclet -- a class that takes as input the documentation-related information that JavaDoc can extract from a set of files, and writes
documentation files in a format specified by the developer. Most example doclets stay pretty close to the original JavaDoc
mission. For example, Sun provides a doclet that can write code documentation in RTF (rich text format, which most word processors
can read) instead of HTML format. Some more adventuresome doclets actually generate new Java code files; for example, the
Swing team internally uses a special doclet to automatically create
BeanInfo classes from
In this article, I introduce another kind of doclet extension; producing documentation intended to be read by HTML or JSP
designers instead of programmers. In particular, the
ServletDoclet class described below produces HTML files that organize the information that any Webpage author would want to know about
a servlet. How do I invoke the servlet from a link or a form? What parameters can I use, and what do they do? What session
beans change state as a result of calling that servlet? What JSPs are associated with the servlet and render its output? You
cannot find that information in standard JavaDoc documentation for a servlet class, and Webpage authors shouldn't have to
scan your source code to deduce what parameters it takes.
Using the techniques described below, you can provide solid documentation to your Webpage authors with just a simple extension
to your normal coding practice. By adding a specific set of tags to your servlet's JavaDoc comments, and running the
ServletDoclet, you can produce comprehensive documentation for your servlet at the touch of a key.