RE: [xsl] standard method of documenting XSLT code?

["Bryan Rasmussen" <bry at itnisk dot com>]

> Anyone done anything with documenting XSLT code, perhaps like the
> <documentation> element in W3C Schemas?

perhaps you would like to look at http://xmlp.sourceforge.net/ using
literate programming techniques, could be applied to xslt, with the lp
namespace elements contained within an <xsl:comment>...</xsl:comment>.

On a side note to this, I'd be more concerned in coming up with standards
for how comments should be written to actually be useful. It seems to me
most comments I ever read are either self-evident, completely
incomprehensible, or just non-helpful(this includes many comments I've
written).
In such cases comments only serve to heighten the illegibility of the code.


to me it's been most helpful if I just do a comment at the top of the most
complex templates, describing what the purpose of the template is and how I
achieved it, like:

<!--This template recurses through the textnode and tokenizes, it calls
itself until the value of the local parameter $stringval = 0 at which time
it applies templates on the following-sibling::name() = the name of the
element we're processing-->

of course others might not like this form of commenting cause it doesn't
tell enough about the inner workings of the code.
as a general rule I've found I hate comments inside of a template.

Anyone out there have opinions on what things are the most necessary to
comment in a stylesheet, and what things can best be left out.


 XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list