Doclet your servlet!

Write better documentation with ServletDoclet

Page 3 of 3

Now you finally have all the tools to do the work. On doclet initialization, you construct ExternalLinks for the external documentation sources. While writing requestBean and sessionBean tags in your HtmlDocletWriter, you check to see if there is a class that can be represented by an external link. To do that, you find the ClassDoc for the bean type. That step is necessary to get the package that the given type is in, using the context of the file to expand simple names such as String into fully qualified names such as java.lang.String. Once you have a package name and a class name, you call a static ServletDoclet method, which checks every ExternalLink looking for the package. Upon finding the ExternalLink that contains the desired package, the ServletDoclet method calls makeExternalDocURL() to build a URL to the documentation for the target class.

protected String getBeanLink(String type, ServletDoc doc) {
    ClassDoc cd = doc.findClassDoc(type);
    if (cd == null) return null;
    
    PackageDoc pack = cd.containingPackage();
    return ServletDoclet.findExternalDocURL(pack.name(),cd.name());  
}
static String findExternalDocURL(String packageName, String className) {
    Enumeration en = sExternalLinks.elements();
    while(en.hasMoreElements()) {
        ExternalLink link = (ExternalLink)en.nextElement();
        if (link.containsPackage(packageName)) {
            return link.makeExternalDocURL(packageName,className);
        }
    }
    return null;
}

Conclusion

Your New Year's resolutions were to get more exercise, take your vitamins, and write good documentation for the Webpage designers who will use your servlet. Will you settle for 1 out of 3?

The ServletDoclet presented herein can make it much easier to write and maintain useful servlet documentation for Webpage designers who may not appreciate reading normal JavaDoc, and couldn't possibly scan your code to figure out what parameters you support. JavaDoc is an elegant solution that integrates documenting with coding, and the ServletDoclet extends JavaDoc to write Webpages your designers can read.

In addition, that example of the Doclet API's simplicity might embolden you to customize ServletDoclet further to your own needs (perhaps adding some more tags that fit your situation), or even to write similar doclets for different purposes. You could, for instance, write a doclet that scans your code for tags that indicate "to do" notes you left for yourself in your code, using custom tags you designed. Or you could write a doclet that reminds you to write documentation by listing all the methods you forgot to document. Better yet, why not write a doclet that counts how many new classes and methods you wrote since yesterday, and reminds you to take your vitamins and get some exercise!

Learn more about this topic

| 1 2 3 Page 3