Re: Source Text Tools

[Guy Laden <guy@math.tau.ac.il>]

Hi all,

Michael van Acken <mvacken@t-online.de> wrote:
> 3. Description is formatted with additional @oxxx commands
> PROCEDURE (list: List.List) Append* (node: List.Node);
> (**
> Adds node @opar{node} to the end of list list @opar{list}.  If
> @opar{node} is of type @otype{List.NodeUp}, then its field
> @ofield{List.NodeUp.up} is changed to refer to @opar{list}.
> 
> @empf{pre}: @opar{node} is not part of any list.  
> *)

I liked this proposal most of the three.
I think theres most to gain by using annotations that have 
a meaning beyond mere formatting.
In this spirit, perhaps pre/post condition lists are important 
enough to have their own 'tag' rather than just using @empf ?
Other candidates for such tags are IN/OUT parameters, and some of 
the annotations that were added to component pascal records and 
methods.

Has any consideration been given to separating the documentation
from the module source? Personaly I find documentation in source
mostly gets in the way while editing/reading and I much prefer 
separate reference documents.

One last idea, how about designing an XML DTD for OOC 
documentation files? XML seems to be catching on and it 
sounds like it provides a reasonably simple framework for 
this kind of project, instead of an ad-hoc design.

Regards,
Guy.