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

[Stephen Eilert]

a r wrote:
> I don't want any API docs automatically generated from source code
> comments - when separated from the code these comments are just a pile
> of useless random notes. Documentation _must_ be written in separation
> from the code. Yes, it is an additional effort, bu if you can't afford
> it simply don't bother writing any documentation.
>   
I think what is meant by "source code comments" is parseable comments in 
the source code, intended for tools to generate and update documentation 
automatically, possibly with their own tags to add semantics. Look up 
Doxygen (http://en.wikipedia.org/wiki/Doxygen) and check out the example 
source code and generated docs. Granted, that's not Scheme, but 
hopefully that's enough to understand the idea. **

It not as if such a tool is going to detect each and every comment 
everywhere and create a useless pile of random comments. That would, 
indeed, be useless. Usually, this type of documentation is brief, just 
giving a general idea of what the function does, which arguments are 
required (and what they mean) and the expected output. How's that 
different from what's being done, for instance, in the sqlite3 egg? 
(http://www.call-with-current-continuation.org/eggs/sqlite3.html)

If you need more than that, then a "manual" is called for. Or even a 
"tutorial". And that can and should be kept in some other location, 
provided it is easily accessible.

If you keep them apart, you cannot see at a glance (let's say, while 
adding features or fixing bugs) if the docs are out-of-date or if 
someone forgot to comment something. Furthermore, the authors have no 
need to look up documentation at all, so the documentation *will* become 
outdated. It's the users that need it, and those aren't always familiar 
with the code to spot the inconsistencies.

Of course, you can keep the docs wherever you want, provided you have 
enough minions you can slap to bring all of them up-to-date :)

Stephen


"Statistics are like humans. Torture them enough and you can make them admit 
anything you want"