Re: Guile documentation

[Andrew Archibald <aarchiba@undergrad.math.uwaterloo.ca>]

; There are a few other code documentation systems out there,
; has anyone given them a good look over?

I looked around recently.  They don't seem to be in wide use.  There
are a few gizmos like doc++ which act like Java's javadoc, usually
only for c++.  The one that seemed most suitable for me was "noweb", a
more-or-less language-independent literate programming tool.  Of
course, literate programming isn't necessarily what we want.  But if
you want to generate source code from the documentation, it would
probably do a good job.  http://www.cs.virginia.edu/~nr/noweb/

; Java has a stardard for lucid programming too which (I think) is taking off
; a bit better. The javadoc tool is powerful because it parses the syntax
; of the actual source, then combines the function and structure definitions
; with comments from the code and cranks out an HTML tree. Java doesn't
; even try to support documentation embedded in the code though and it's
; still, at heart, a compile-link-execute type language (though it does do
; amazing things with modular dynamic linking that still spin me out.

Yeah, kawa is a very interesting system.  A scheme scripting language
for the Java VM that is on an equal footing with the Java language.
You can interactively load up a random class, ask it what its methods
are, and call one.  Nifty.

But there's a good point here --- javadoc does a better job because it
knows the structure of the language.  A scheme documenter that knew
the structure of the language would be handy too.  Having a doc string
for every function and every variable would be very nice.  Of course,
there are performance issues... regardless, using a doc generator that
knows about scheme and guile c would probably give better docs than a
generic one. 

Andrew
aarchiba@undergrad.math.uwaterloo.ca