Subject: Re: [xsl] xsl/xslt coding standard|
From: Francis Norton <francis@xxxxxxxxxxx>
Date: Sun, 18 Aug 2002 08:44:18 +0100
James Fuller wrote:
- XHTML is a native format one can use for documentation, so there is a
standard native option that is close enough to the HTML we all know and love
( instead of XSLT or XML schema specific, niether of who's core requirement
is to be a language for documentation or meta data )
XHTML is not a language whose core requirement is to be a language for documentation, either. In that sense, DocBook is more "naturally targeted" at documentation than XHTML is. If we're going to say that XSLT and XML Schema are not designed for documenting code so we shouldn't use it for documenting code, then by extension we need to find/develop some system that is specifically designed and optimized for commenting code.
Personally, I'd be in favor of going as far as a W3C-standardized
XML-documentation format beyond normal <!-- comment --> tags. That way,
just as with JavaDoc, you could easily parse it into a separate document
to serve as documentation. The SVG folks are using RDF as a
documentation format, which has its ups and downs.
Of course, before we do that, I have to ask, exactly what are we commenting? We already have a system for unstructured comments, <!-- -->. If we're talking about structured, parsable documentation, the first question to ask is what exactly we're documenting. With JavaDoc, it was fairly easy. Methods and classes had been around long enough that figuring out what to document about them was fairly straight-forward. With XSLT or other XML technologies, what exactly are we commenting? That's a question we have to ask before we figure out how to comment it. Otherwise, we're just reinventing <!-- -->, which has already been done.
-- "Never mind manoeuvre, go straight at 'em." - Admiral Horatio Nelson