hi,

I've done some looking around at automated documentation programs. There's HeaderDoc, which Hans-Christoph mentioned, AutoDoc, Doc++ and Doxygen. Of all of those I would go toward Doxygen, as it runs on Linux, Windows, and OSX and is GNU GPL, while HeaderDoc is APSL. Doxygen is used by KDevelop and Mozilla for their source documentation.

doxygen is the standard, that's for sure. while it provides a quite complete and well to navigate source documentation it lacks a bit in visual elegance (yes: good looking matters :-). and it seems to be made for c++ rather than c - but that's not really a problem.

what speaks for headerdoc is that it only requires you to edit the header files: .c files remain small.

the APSL is ok. (especially as we do not seek to distribute the software - we just run it). but it is a problem that headerdoc seems to be mac-only (maybe just a matter of compiling it for linux).

I haven't seen anything that gives wiki ability out of the box, but it should be easy to add some sort of wiki comment system by means of links. The auto-generated docs act as a skeleton that is fleshed out with a wiki. I don't have a wiki server at my disposal, so I can't give an example of it, but Doxygen is very configurable and allows custom footers that could include links to a wiki via some sort of server side scripting.

links are the only solution. as the documentation is generated from the source, commenting directly would mean editing the source. it should be fairly easy to hack up doxygen to provide a link with every row of the member data and function documentation. (or maybe just in the footer as you propose)

some wikis propose that you generate a new entry when no entry for a specific name is found, so maybe we just need to link to a specific page for every name and have a fallback when the page does not exist.

lg martin

I've written a brief Doxygen config file and created documentation out of the 0.38 CVS HEAD src directory so you can get an idea of Doxygen. I did not alter the source files at all, so the commenting is *very* sparse. The Test: http://www.0x09.com/temp/doxydoc/html

The only actual work I did to get the test: http://www.0x09.com/temp/doxydoc/

Doxygen help documentation http://www.0x09.com/temp/html

=== likage: === HeaderDoc http://developer.apple.com/darwin/projects/headerdoc/

Doc++ http://docpp.sourceforge.net/

Doxygen http://www.doxygen.org/

AutoDoc http://www.oche.de/~akupries/soft/autodoc/

Let me know all y'all's thoughts on it, and I'll see what I can set up so we can slowly start improving the documentation.

Cheers, Ian

---

PD-list@iem.at mailing list UNSUBSCRIBE and account-management -> http://iem.at/cgi-bin/mailman/listinfo/pd-list