Re: [Chicken-users] documentation issues...

[Elf]

On Thu, 14 Feb 2008, a r wrote:
<snip>
> BTW, I agree with elf that extracted function signatures (+ one line
> descriptions) could be useful for certain applications (editor/IDE
> support, interactive mode help etc.). This however has nothing to do
> with an end-user documentation.

erm, thats not actually what i was saying.  i would be generating the 
interpreter docs, ide/editor docs, pdf, html, texi, whatever docs all from
the same single source file.  a) its the least amount of work for the devel
to keep track of.  b) its easier (and more likely) to keep one thing up
to date than to keep six things up to date.  c) it ensures consistency 
in content (and some in format) between docs , and d) its easiest in terms of
batch generation, methinks.

the calling convention plus one line desc is commenting before every proc,
macro, and var (although for vars ill sometimes just do it at the end of the
line as a single line) in the source.  its not enough to know everything
thats going on, nor is it enough to get in the way of the code.  the point
of doing so is a) to remind myself whats going on if i have to go back to it
and b) to make it easier for others who might read it to trace it without
knowing anything about it beforehand.

-elf