"Document Your Code! Document Your Code!!"
This is one of those lessons hammered into most Computer Science majors about three days into their first code class--and one quickly forgotten by most within the first eight days. The benefits of documenting code are obvious-from being able to remember what you worked on several months before to making sure that someone who inherits your code can have a basic clue about what you were trying to do. Problem Summary
: Documentation is difficult to write, and even more difficult to maintain. Wouldn't it be convenient to have self-documenting code to which you could add custom documentation--and have all of that display in a readable manner, on demand? Solution Summary
: In XSLT, you can take advantage of extensibility, a known document structure, and transforms to produce self-documenting XSLT templates.
Documentation, however, can be time-consuming to write, especially because there are really two types of documentation. User documentation describes the methods and parameters of an object, or the description of how a given class works. Diagnostic documentation, on the other hand, is intended to either explain why a given routine or variable is used or why something is commented out-its purpose serves as working notes for a piece of code, something that would be useful for debugging an application if it doesn't work properly (or upgrading it if it does) but which may not be appropriate for the final consumer of the product. User documentation for a VCR would tell you which buttons to press to make it work (and how to prevent the blasted clock from flashing "12:00" all the time), while diagnostic documentation would tell a technician how to replace a malfunctioning module.
Because the difference between user and diagnostic documentation isn't always immediately obvious, developing documentation (whether using XSLT or any other programming language) often tends to be a somewhat haphazard process. XSLT has the advantage of a known document structure that makes it easy to both determine functionality and retrieve information without necessarily needing to write any explicit documentation. By augmenting this with a distinct documentation "namespace", you can actually create fairly extensive documentation for all your XSLT routines.
The JavaDoc program included with most Java implementations is a model. JavaDoc examines the overall class structure and retrieves primary class, method, property and event names exposed by the class, as well as other relevant structural information, such as parameter names and data types. JavaDoc then maps the information into an HTML file (something which should be ringing bells in the head of any XSLT developer), and indicates where the class fits in the overall framework's architecture. However, by following a specific format for comments in the source code, it is possible to create very rich sets of documentation that go beyond describing the core structure, and get into detailed explanations about how to use the class in practice.