[xsl] commenting and documenting XSLT (small survey)

Subject: [xsl] commenting and documenting XSLT (small survey)
From: <christof.hoeke@xxxxxxx>
Date: Thu, 8 Jul 2004 11:16:42 +0200
hi,
my question first...

In what format do you write the (XML) comments in your XSLT stylesheets? (if any ;)
What do you think is better: reStructuredText (ReST) format, or Javadoc style? Or what other format? Which one is more likely to be used? 


background:
===========
I developed an xsldoc app which basically works similar to how javadoc works for Java sourcecode (there are a few other tools that do the same). Every toplevel XSL element may have a (XML-)comment right before it which then will be used as a comment for the element. Additionally some package documenting files are processed as well (for details see http://cthedot.de/pyxsldoc).

The comments themselves may be in one of two formats and thats what i like to know what people think about it:

Javadoc style
-------------
I started writing the XML comments similar to javadoc comments with HTML and @tags, example:
<!-- 
	<p>a template which is <b>important</b> because</p>
	<ul>
		<li>this is an example</li>
		<li>just like that</li>
	</ul>
	@since 1.0
	@version 0.1
-->

Problems with that approach are obvious:
* difficult to write (if not used to it) but also to read while working in the stylesheet
* no validation of HTML possible as no IDE (at least to my knowledge) does it (and the xsldoc app is producing XHTML, so it *should* be valid)
* (and currently not all elements are processed by xsldoc)

Main advantage:
* at least Java programmers know how to write the format


reStructuredText (ReST)
-----------------------
while looking for an easier way to write structured comments I thought about a simple wiki format. as there are lots of them I stumbled accross ReST http://docutils.sourceforge.net/, from the website:

	The purpose of the Docutils project is to create a set of tools for processing plaintext
	documentation into useful formats, such as HTML, XML, and TeX. Includes reStructuredText,
	the easy to read, easy to use, what-you-see-is-what-you-get plaintext markup language. 

so it perfectly does what i was looking for. I chose ReST as the default comment format for XSLT comments and also the additional package documentation files (e.g. overview.txt which directly compares to overview.html in javadoc).
the above example in ReST would therefore be:

<!--
a template which is **important** because

* this is an example
* just like that

:since: 1.0
:version: 0.1
-->

Again there are a few problems:
* comments have to start on the first column of the file 
* as -- is forbidden in XML comments ReST elements that use that construct cannot be used (which basically is just a table, all other markup can be written with substitution characters like == or ~~)

Main Advantages:
* very easy to read so more useful while working on the XSLT and more likely to be written at all
* (ultimately possible to be converted to other formats than just XHTML although only that is used by xsldoc at the moment)


In my opinion using ReST in XML/XSLT comments is better but maybe that depends on if you are a Java or Python programmer? 
What do you think?

thanks a lot (and sorry about the long post)
chris

Current Thread