Re: using doxygen to document gobject/gtk classes?

[Tristan Van Berkom <tvb gnome org>]

On Tue, Nov 17, 2009 at 12:22 AM, Brian J. Tarricone <bjt23 cornell edu> wrote:
> Hi all,
>
> I'm in a situation where I'd like to use doxygen (and not gtk-doc) to
> document some GObject-derived classes.  Does anyone have any
> experience with this and knows of any tricks to use to make the output
> more useful?  I found one link via google[1] that referred to this,
> but it didn't have much useful info.
>
> Specifically, here are the problems I'm having:
>
> 1.  If I have a "final" GObject class (only the typedef for the struct
> in the .h file, with the struct definition in the .c file), the symbol
> is showing up as "struct _Foo" in the doxygen docs, instead of just
> "Foo".
>
> 2.  I can't seem to figure out how to get documentation for signals
> and properties into the docs.
>
> 3.  Possibly related to #1, I'm not sure how to make the docs
> understand the class hierarchy.  The \extends command in doxygen
> doesn't seem to be working for me.

I doubt that what you are trying to do is worth your while.

For instance, signals and properties and I would dare say
even the class hierarchy - is not at all derived from source code
scanning; gtk-doc compiles a tool against your code to programmatically
introspect the signals (Im sure at least about the signals), and probably
also the properties and class hierarchy. The compiled tool creates some
templates, and then, insert black magick with sgml scanners/lexers/forms and
doxygen and html stuff that a simple C programmer like me would not
understand ;-)
... THEN you get the docs.

AFAICS, any attempt to get GObject documentation straight and "objecty"
with doxygen, would be a world of work, that would be a direct duplication
of the work already done on gtk-doc (which btw, works alot better than
it did 4 years ago).

Heres an off the wall idea: use gobject-introspection combined with some
code generator and generate a C++ or javascript binding to your code,
and run that stuff by doxygen instead ;-)

Cheers,
       -Tristan