If Spice is a language that ties in closely with XML and HTML, wouldn't
it be sensible / useful to develop an XML-based doc tagging system? That
way your REF files could be totally automatically generated. If fact,
you could extract the relevant XML and pass it through a bunch of XSLT
translators to produce any manner of documentation you want.
Javadoc is the obvious (non-XML) equivalent. An XML version is available
for MS Visual Studion (inc. C++):
http://msdn.microsoft.com/msdnmag/issues/02/06/xmlc/default.aspx
Anyway, my point is that with a bit of imagination you can probably
auto-generate REF, TEACH and EXAMPLE documentation straight from source
code with a couple of helper files (like the package-summary.html (??)
file that adds documentation to a package in Java).
It might be nice to allow the user to choose to inline their
documentation or store it in a parallel file. Sometimes I get fed up
scrolling through all the doc sat in the middle of my code.
Dave
|