AW: AW: commenting and documenting XSLT (small survey)

> > also otherwise XML comments are totally superfluous, are they not?
>
> No. xml comments have purposes, they for example allow you to
> comment out
> bad (non well formed) fragments until you have time to fix
> them (or just
> to record what was there before you removed it) also they are good for
> unstructured, or non-xml structured small comments (eg CVS
> identification lines) but your example had deeply structured comments,
> and for that XML is much better suited than xml-comments.
>
> XSLT was designed to allow you to mix xslt elements and xhtml elements
> freely within the stylesheet. the xhtml is ignored if you run
> the code,
> and its trivial to write a small stylesheet that swaps things
> around and
> produces well structered xhtml documentation, based on teh xhtml
> fragments from the stylesheet and some verbatim or "tree view" of the
> code fragments.
> see for example some examples here:
>
> http://www.dpawson.co.uk/xsl/sect2/documentation.html
>
> David
>

i do acknowledge the method using elements in another namespace for
documentation but the problem is the same as using Javadoc style comments:
- It is quite an effort to write
- very difficult to read (not meant to be readable at a glance but comments
should be IMHO)

so I guess not a lot of people actually write documentation that way as it is
quite a work to do. Also it does not really help while working in the
stylesheet itself. using reStructuredText in XML comments does not have this
problem. i agree that one should not write deeply structured comments this
way, external documentation in another file might be better for that anyway.
but for the purpose of the xsldoc tool that is exactly what gives a good
overview of an xslt package.

chris