On Thu, Feb 14, 2008 at 9:28 PM, Stephen Eilert <[EMAIL PROTECTED]> 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. _______________________________________________ Chicken-users mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/chicken-users
