Re: Scheme documentation question

[Tel <telford@eng.uts.edu.au>]

> I don't like this idea at all.  From a software-enginering maintenance
> and evolution perspective, we want to increase the coupling between the
> code and the documentation.

We also want something easy to use and that means easy to parse.
You can always write a parser that checks the existence of documentation
for each function or finds documentation that doesn't seem to belong
that any function. This can easily be automated without special tricks
or confusing bends to the normal scheme structure.

> > Possible extensions:
> > 
> > (document-variable VAR DOC-STRING 
> >                    &opt CHAPTER-HIERARCHY 
> >                         SEE-ALSO-LIST)
> > (document-function FUNCTION DOC-STRING 
> >                    &OPT PARAM-DESCRIPTION-ALIST 
> >                         CHAPTER-HIERARCHY 
> >                         SEE-ALSO-LIST)
> > 
> 
> Ugh. Now you're repeating the signature of the procedures, too.  Very
> error prone, and very bad.

I don't like repeating the signatures, firstly because they are easy
to extract from the actual definitions (and their presence in the definitions
is mandated by the scheme standard), secondly because one gets out of
date with the other.

On the opside though, you can scan for correctness of the documentation
in an automated manner. It also gives you the power to document each and
every parameter with it's own description, which is something no other
method offers (dunno how useful that would be though).

	- Tel