gtk-doc vs Doxygen results

[Enrique Arizon Benito <earizon unizar es>]

Two weeks ago I wrote asking for some particular system used for 
documenting dia source code (Doxygen or similar tool).
Someone pointed me to gtk-doc while I pointed to Doxygen and I have 
also seen in the change logs that Doxygen style documentation was added 
by Lars Clausen.

Well, after comparing both of them (gtk-doc and Doxygen) I have found 
gtk-doc the most suitable for dia. Curiosly the gtk-doc systems looks to 
be not really well documented, more even when compared to Doxygen and 
the gtk-doc-list 'moves' really slowly but on the opposite I found next 
advantages:

- gtk-doc works well when parsing gtk code. Someone on the gtk-doc-list 
even pointed that it used the gtk introspection capabilities (don't ask 
me what introspection really means in this context exactly).

- What is more important, some GTK/Gnome tools look to be adapted to 
gtk-doc. For example devhelp (http://www.imendio.com/projects/devhelp/) 
used in the Anjuta IDE. So Doxygen style documentation will fail.

P.S.:
I think the documentation system is really important when the code 
grows since there is no easy way of expresing 'desing patterns' with C 
code (neither with any other programming language). For example resource 
tricks like pooling of objects or drawing-avoidance when zoom is too 
small, 'marshalling' of object/diagrams, where in the ModelS View 
Controler hierarchy belongs an object, .... can just be documented with 
human text, but even the best designed API will give not hint about them.

Enrique Arizón Benito

Software Developer and Network Administrator