[PD] Re: [PD-dev] API documentation

martin pichlmair pi at attacksyour.net
Thu Jan 13 08:44:02 CET 2005


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


> 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 at iem.at mailing list
> UNSUBSCRIBE and account-management -> 
> http://iem.at/cgi-bin/mailman/listinfo/pd-list

More information about the Pd-list mailing list