Re: generating a manual from annotations in source code

["Gary V. Vaughan" <gvaughan@oranda.demon.co.uk>]

Clark McGrew wrote:
> I would like to see a documentation property attached to both scheme
> and  primitive functions (and compiled into the executable).  I find
> it very useful when I'm hacking around to be able to get a quick
> synopsis of a function.  But, if the documentation is compiled into
> the exe, then the doc strings should be short.

I would tend to think this adds unnecessary bload to the binary, and
would mean that the doc strings for subr's (implemented in C) and (in
the future) byte-compiled scheme functions would be stored (and thus
accessed, wrt lookup code) differently.

I like the way emacs stores its doc strings in an indexed file generated
at (byte) compile time -- despite the reservations some of you guys
have...
 
> I'd also like to see the reference documetation included in the
> source.  By source I mean a .h, .c, or .scm file.  On the other hand,
> I'd hate to see a move to literate programing since (I feel) it make
> code completely unreadable.

Agreed, on both counts.
 
> Another problem with documentation in the source is that functions
> tend to be in a "random" order.  This could be solved by adding a
> section tag to each annotation.
> 
> This isn't a new idea, but how about a solution like this.
> 
> In C:
> 
> /*
> (REFERENCE scheme-name (section-info)
> This is for detailed reference documentation that describes how to use
> the function.  It goes into a user reference manual.  The scheme-name
> is the name of the scheme function being documented.)
> 
> (PROGRAM C-name (section-info)
> This is for detailed implementation documentation.  It goes into a
> programmers reference manual.)
> */
> 
> static char s_scheme_func_doc[] =
> "A short text synopsis attached to the documentation property"

I really like this!  But, for the reasons cited above, I would rather
add:

/*
(DOCSTRING
A short text synopsis attached to the documentation property)
*/

> In scheme:
> 
> ;(REFERENCE scheme-name (section-info)
> ;  The detailed reference documentation goes here.)
> (define scheme-name
>    (lambda ()
>         "A short synopsis goes here."
>         ...))

This is cool, but to avoid the inevitable slowdown of parsing all of
these embedded docstrings we *really* need byte-compilation which would
extract the string to an index file of some sort.
 
This is not just a "me too"!  The thing that I thought would be really
cool about this, is that the manuals and doc strings could be cross
referenced by the extraction process... that is the doc string could
have appended, e.g. "(ref manual pp.123, section 4.5)", or the reference
manual could point out at the explanations in the user manual, e.g. "The
use of this function is described in the user manual pp.. etc".

> [[snip]]
>
> Cheers,
> 
> Clark

Yup!

Cheers,
	Gary V. Vaughan
begin:          vcard
fn:             Gary Vaughan
n:              Vaughan;Gary
org:            Aethos Communication Systems ltd.
email;internet: gvaughan@oranda.demon.co.uk
tel;work:       01454 - 204411
x-mozilla-cpt:  ;0
x-mozilla-html: FALSE
version:        2.1
end:            vcard