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"/>
Michael Kay
Exactly the technique I use, with additional use of x:doc=".." on function and
template heads to carry out the same purpose. Then a simple script can generate
Javadoc-like HTML reference material (including of course the 'Javadoc' for the
script that generates the 'Javadoc' ;-) It you want some sort of styling in the
attribute-borne comments, then you can build some simple encoding scheme.
For more complex structures, they'll have to be in a foreign ('documentation')
namespace at stylesheet toplevel and you'll have to use adjacency to associate
deeper comments and functions/templates, or cross-ref through some form of id.
A similar technique can be used to embed examples and testcases. In some of my
work on document layout <ex:example>layout declaration tree</ex:example>
structures can be placed as top-level children and then picked up by a
stylesheet to generate code and result 'atlases' of layouts available.
It all drives towards placing all relevant information as close together as
possible and *not* in hosts of separate files that need to be kept in strict
coherence.
--------------------------------------------------------------
John Lumley CEng FIEE |
Hewlett-Packard Laboratories | Phone: +44 117 312 8743
Long Down Avenue | E-mail: John(_dot_)Lumley(_at_)hp(_dot_)com
Stoke Gifford | Fax: +44 117 312 9937
BRISTOL BS34 8QZ, U.K. |
------------------------------------------------------
Hewlett-Packard Limited registered Office: Cain Road, Bracknell, Berks RG12 1HN
Registered No: 690597 England.
--~------------------------------------------------------------------
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
To unsubscribe, go to: http://lists.mulberrytech.com/xsl-list/
or e-mail: <mailto:xsl-list-unsubscribe(_at_)lists(_dot_)mulberrytech(_dot_)com>
--~--