What about just using custom attributes rather than comment elements? It
means your documentation is not arbitrarily structured, but it can at least
have a structure that matches the stylesheet itself, without interfering too
much with the output tree.

<xsl:stylesheet version="1.0"
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:doc="doc:documentation"
	xsl:exclude-resultset-prefixes="doc"
	doc:comment="This stylesheet handles blah elements"
>

<xsl:template match="blah" doc:comment="Handles each blah">
	<xsl:param
		name="blah-type"
		doc:comment="the type of blah handled"
	/>
	<xsl:for-each
		select="blah-child[@type="$blah-type]"
		doc:comment="for each child of the selected type"
	>

etc...

An XSLT processor should be happy to ignore these comments (isn't that
right?) while a simple XSLT could turn these comments into a nice
"pretty-printed" stylesheet.

Outside of a template, elements are unproblematic, and as Jeni suggested
they should probably use html elements (like in JavaDoc) for occasions where
more structure is needed. I don't think there's a need for full-on "DocBook"
structure for commenting parameters, variables, templates etc, because
mostly these comments could be added as @doc:comment attributes to the XSLT
elements themselves.

<doc:comment>
	<p>See also:</p>
	<ul>
		<li><a href="blah blah blah">Blah blah blah</a></li>
		<li><a href="something else">Something else</a></li>
	</ul>
</doc:comment>

Con


 XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list