> If you pretended that the C function documented above was a 
> XSLT function and invented some simplified syntax on the fly 
> (as I'm about to do), you'd end up with something like:
> 
> ------------------------------------------------------------
> <x:doc xmlns:x="http://example.org/documentation">
> $res::                  Result tree.
> $fo_doc::               #FoDoc to which to write output.
> $fo_tree::              Pointer to generated FO tree.
> $area_tree::            Pointer to generated area tree.
> $continue_after_error:: Whether to continue after a formatting error.
> $debug_level::          What debugging output to generate.
> $error::                Indication of any error that occurred.
> 
> Generates FO and area trees from $res result tree.
> </x:doc>
> ------------------------------------------------------------
> 
> which is a lot easier to write, read, and update than putting 
> DocBook or DITA into the stylesheet and is still sufficiently 
> structured that, with some XSLT munging this time, you can 
> get from there to DocBook or DITA and from thence to HTML or 
> to whatever.

But do we want users to have to learn yet another markup language?

It seems to me that the obvious place to document a function parameter is an
extension attribute on the xsl:param element:

<xsl:param name="fo_tree" x:doc="Pointer to generated FO tree"/>

Regards,

Michael Kay
http://www.saxonica.com/
http://twitter.com/michaelhkay