The restriction is only a restriction on the authoring of the
documentation, not where it appears. With the method I suggested if you
put a (namespaced) id attribute on any element internal to the template
then you can sticka <xhtml:span (or div or p or anything elese)  with a
namedspaced ref attribute and that documentation will be taken as
documenting the xslt instruction with the id, and shown just before that
instruction.

So the only thing you can't directly document using this method is a
literal result element, but that isn't so much of a restriction as you
can always use an emty xsl:text to carry the documenttation.

Do you mean the doco 'external' to the template now
idrefs into the template? Is that it?

Sneaky - and effective! Tiny bit more processing than weaving,
but meets the need.

<xhtml:p>This template matches foo and makes a table</xhtml:p>
<xhtml:span doc:ref="aaa">
this is a literal result element to make a table
</xhtml:span>
<xsl:template match="foo">
...
<xsl:text doc:id="aaa"/>
<table>
<thead>...

</xsl:template>

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk