Newsletter sign-up

View all newsletters

Sign up for our technology specific newsletters.

Enterprise Java

Email Address:

Doclet your servlet!

Write better documentation with ServletDoclet

By Jeremy Roschelle, JavaWorld.com, 03/02/01

So you've written that killer servlet, and now it's been discovered. Congratulations!

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 Bean classes.

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.

 

About Us | Advertise | Contact Us | Terms of Service/Privacy

Copyright, 2006-2008 Network World, Inc. All rights reserved.