I consider it a best practice that all JSP tag libraries should have documentation available from their associated URL.
As a tag library descriptor (tld) is in XML, and includes the ability to associate documentation with tags, the option is available to generate a default set of documentation directly from the descriptor.
Generating Docs with XSLT
Customising the look-and-feel is simply a matter of altering the presentation in the template. This stylesheet transformation could easily be included as part of an automated compilation process, e.g. with Ant.
There are some limitations:
- info elements can only be associated with the library and individual tags, not attributes
- info elements can only contain plain-text, not markup
These limitations can be easily removed.
Rich Tag Library Descriptors
Here is an example of a 'rich' tld. It has info elements associated with attribute elements. It also contains richer markup inside the info elements for bold, italicised and underlined text, as well as paragraphs and links.
Here is a pre-processor stylesheet that turns 'rich' tlds into standard tlds suitable for deployment. Sample output (you may have trouble viewing this in IE, as it fails to fetch the DTD from java.sun.com) which should be identical to the original.
Again, both of these steps could be automated using Ant.
There's some cross-over with RDDL here as the URI associated with a Tag Library descriptor becomes the namespace URI for elements associated with that library.
There may be bugs in these stylesheets, but they've worked successfully with the descriptors I've created so far. Feel free to take them, alter them, and generally do what you want with them. They're Public Domain.
I came across a link to Taglibtools this morning. It's capable generating HTML documentation and Java source for a tag library from the taglib descriptor alone. The generated code is much nicer looking than mine!
A quick look at the example and source looks like the generated docs use only the basic TLD format, so its not quite as flexible as my 'richer' taglibs. Rather than using XSLT it looks like its using a DOM package to walk through the descriptor.
I still think the XSLT based approach is simpler (less code if nothing else), and that could be easily extended to generating Java source as well if necessary.