Re: generating a manual from annotations in source code

[Andrew Archibald <aarchiba@calum.csclub.uwaterloo.ca>]

karlheg@inetarena.com (Karl M. Hegbloom) writes:

> >>>>> "Mark" == Mark Galassi <rosalia@cygnus.com> writes:
>     Mark> We are not describing how the implementation works.  We are
>     Mark> describing the various APIs and how the programmer should
>     Mark> use them.
> 
>  But isn't that almost the same thing?  An understanding of how it
>  works internally can assist in designing good programs around it.

It can indeed; but for the moment what we need are docs that explain
how to write programs at all.  The requirements for these are somewhat
different, for several reasons.  First, there are standards,
questsions of portability and whatnot.  Writing pure scheme, the best
"API reference" is probably RnRS.  Second, there's the question of
simplicity.  If I want to write a guile scheme extension, I'd rather
learn a ten-page API doc than a thousand-page internals doc.  (Yes, a
thousand pages --- for true literate programming, the docs include the
complete source code as a small fraction of their volume). 

>  For instance, I just learned that in Emacs, it's more efficient to
>  use (car (car (cdr ls))) than to define a C subr `caadr', because the 
>  lookup and dispatch time is slower for that subr than executing the
>  varref, cdr, and two car byte code instructions.

For instance, I just wrote a tiny C program to run my CDROM drive from
the login prompt.  I didn't know about ANSI/K&R, I used functions
rather than macros or __attribute__((inline)) (or whatever that is),
and I didn't even design it so GCC would output minimal bytecodes; and this is
good.  It would have taken me a long time to learn all that from a GCC
internals doc.  Oh, the performance is fine, BTW. 

>  Perhaps there are things of this nature to be learned about `guile'
>  through an understanding of its implementation internals.

By all means.  Internals docs are really useful; I wouldn't try to
write a speed-tuned scientific computation package without knowing all
about the internals of my compiler (and hardware, and OS).  But what
we need right now (that is, what our users are asking for) is API
docs.  Well-documented source code is decent as internals docs.

Andrew