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"
_______________________________________________
Chicken-users mailing list
[email protected]
http://lists.nongnu.org/mailman/listinfo/chicken-users
