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

Here is an XSLT stylesheet that will transform any tld into an HTML page. Sample output for the Jakarta input tag library.

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 stylesheet that generates richer documentation from these files. And some sample input and sample output Note that the stylesheet will also work with ordinary tld files.

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.

Further Thoughts

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.

Warning

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.


Update (28/11/2002)

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.

Add new attachment

In order to upload a new attachment to this page, please use the following box to find the file, then click on “Upload”.
« This page (revision-1) was last changed on 28-Nov-2002 04:28 by unknown [RSS]
G’day (anonymous guest) My Prefs


Referenced by
Main

JSPWiki v2.6.0 [RSS]