XSLT Documentation Technique
A similar technique can easily be applied to XSLT documents, first by analyzing the document's general structure and then by using a doc: namespace extension to annotate the transformation. Interestingly enough, the process to generate this document is itself an XSLT transformation--an example of a style sheet being applied to another style sheet.
In looking at such style sheets, it's worth examining the basic structures that would be useful in documentation. Table 1 lists the useful style sheet pattern structures
These elements make up the bulk of the "skeleton" upon which an XSLT document is based, and as such serve as the analogs to methods and properties that you expect to see in more traditional programming languages. Note that this set of tags differentiates between matched and named templates--for example, those that have <?XML:NAMESPACE PREFIX = XSL /><XSL:TEMPLATE match="foo">and <XSL:TEMPLATE name="bar">in them. This distinction is important, especially in situations where you're dealing with imported or included files, since such files together often can form a rudimentary framework of XSLT objects.
However, by themselves, these elements will provide only a rudimentary form of documentation, much like JavaDoc working on a generic class will provide the interrelationships, but they will be unable to describe the purpose of functions. Documentation in this regard is meta-information-it describes the code. Unfortunately, machines are notoriously bad at determining intent they can tell you what things go where, but the phrase "why?" is considerably harder to code.
Thus the second aspect of documenting XSLT is to provide some kind of additional annotation to those elements that you want to be publicly exposed. In this article, I recommend creating a distinct namespace (here I'm using the prefix doc: but of course that can be changed if you already have such a prefix collision). The namespace then contains elements and attributes that can both describe the "why" of a given XSLT document, but that can also be used to determine what specifically should be exposed. Table 2 lists the various doc: elements and attributes that I've used in this specific implementation of a documentation class.
As a simple example, the following XML code provides a document summary node that could be picked up by the documentation.xsl stylesheet:
<doc:title>Text To Node Conversion</doc:title>
the Text To Node Conversion converts a
delimited text file passed into the
parameter parse_text parameter
as a string into a series of XML records.
<!-- more code -->