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