Re: gtk-doc vs Doxygen results

[Lars Clausen <lrclause cs uiuc edu>]

On 1 Sep 2003, Enrique Arizon Benito wrote:
> 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.

Very little, I was mostly experimenting.

> Well, after comparing both of them (gtk-doc and Doxygen) I have found
> gtk-doc the most suitable for dia.

Thanks for taking this time to examine the two!

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

In know how introspection works in running code (it allows objects to
examine what fields and methods they have), but to use it in documentation
extraction is interesting.

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

It could be a boon to be able to use those.

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

I agree, and I try to add documentation when I can.  I unfortunately
totally don't have the time to do it comprehensively.  Some docs are at the
Dia Twiki, but much less than I'd like.

-Lars

-- 
Lars Clausen (http://shasta.cs.uiuc.edu/~lrclause)| Hårdgrim of Numenor
"I do not agree with a word that you say, but I   |----------------------------
will defend to the death your right to say it."   | Where are we going, and
    --Evelyn Beatrice Hall paraphrasing Voltaire  | what's with the handbasket?