Re: gtk-doc vs Doxygen results



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?



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]