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