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

[a r]

On Thu, Feb 14, 2008 at 9:28 PM, Stephen Eilert <address@hidden> wrote:
> 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. **

Yes, I meant Doxygen and similar tools. They inherently encourage a
programmer to write a bad documentation. And there are several reasons
for this:
1. limited space,
2. limited document editing resources (no tables, diagrams etc)
3. people generally write better documentation when they are not
looking at the source code (it is simply easier to imagine what a user
needs if you stop staring at your "cheat sheet"),
4. programmers who write Doxygen documentation feel relieved from
writing good documentation (they have filled in all required forms
after all).

>  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.

The problem is, that before plunging into API you should be able to
find a description of the module itself. I have yet to see Doxygen
generated docs that contain a "big picture", description of data
structures, protocols, examples and an API summary (not just a plain
list of functions).

I really much more prefer reading a few paragraphs describing what the
module is for rather than wading through the API reference. Look at
SRFI documents - most of them are pretty good examples of how the
documentation should look like.

>  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.

I agree it is a tedious work. But don't cheat yourself you can skip
this task by using some "magic".

>  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 :)

This is a common problem with the documentation, which it's not caused
by tools but by people and policies, though. If you hate writing
documentation you can always upload the commented source code to the
web. IMHO (especially for scheme code) it is a better solution than
using Doxygen or similar tools.

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.

-r.