Re: Source Text Tools

[Mike Griebling <grieblm@trt.allied.com>]

Guy wrote:

> 
> 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.

I agree that this is messy, however, with a good source browser
tool which extracts the essential source code definitions and/or
produces "pretty-printed" output, this is no longer an issue.

BTW, when my preference for commenting the code runs more toward
a LaTeX-style command structure.  Advantages are that no explicit
font-setting commands are included in the source and, personally,
I find it much less intrusive than all the other formatting mark-up
which I've seen examples of up to now.  There is also a powerful
built-in mathematical language which could be used to describe
algorithms quite neatly.

We used a LaTeX-style markup in one of the projects which I worked
on (an embedded environmental control for the Boeing 777 aircraft
which was written in Ada).  Most designers really liked the mark
up and the source code was still fairly legible.  It was definitely
nice to be able to press a button and see formatted documentation
complete with nice tables and equations.

Michael