Re: [gtk-list] Re: Experimental GTK DocBook documentation

[Greg Badros <gjb cs washington edu>]

Kevin Handy <kth@srv.net> writes:

> At 11:23 PM 9/15/98 +0100, you wrote:
>
> What I would find nice, would be to be able to generate new
> documentation from the source alone, without having to do
> additional changes afterwards. If the comments in the program
> were coded in a standard format, then this should be easy.
> 
> This would require adding comments to the source code, which
> would be a good thing in my opinion. Putting the description of
> each function in the source would be a big help to someone
> trying to figure out how it works/what it does. Also a change
> to a functions interface would automatically change the
> documentation. And if we want to change the overall format
> of the documentation (bold vs underline function names, etc),
> then it would be just a change in the build scripts.
> 
> The end user should just be able to type 'make documentation'
> to get a usable reference guide built.

We have a system and a perl script that does this for Scwm -- it's been
really useful both for generating documentation and for guaranteeing
some simple invariants in the source code that are outside the scope of
the C language.  See:

http://huis-clos.mit.edu/scwm/

for the distribution which contains the script and the source code with
the embedded documentation.  The page also contains a link to the
extracted documentation available at:

http://www.cs.washington.edu/homes/gjb/scwm-doc/

Greg J. Badros
gjb@cs.washington.edu
Seattle, WA  USA
http://www.cs.washington.edu/homes/gjb