gobject introspection and gtk-doc

[Michael Lawrence <lawremi iastate edu>]

Hi,

There's been a lot of discussion about GtkCanvas, but I've heard little 
about another planned feature for GTK+: introspection. I think that 
gobject introspection would greatly facilitate the language independence 
of GTK+ and gnome.

I believe there are plans for scraping the introspection metadata out of 
the header files, like pygtk does for its defs files. Obviously, the 
header files do not contain all of the necessary information, like 
in-out parameters, memory ownership, etc. These require manual human 
annotation of the metadata.

My idea is, why not annotate the header files (or C) files themselves 
with this information? It could be integrated with gtk-doc, so that the 
information could be presented in a standard way in the documentation. 
For example, there is no standard, fixed way of saying that a parameter 
is meant as an "out" parameter in the docs. Another example would be 
whether a return value is owned by the caller. If this stuff was added 
to the gtk-doc annotations it could be used both for generating metadata 
blobs as well as the documentation.

The metadata would require much less human maintenance (perhaps none) 
and the documentation would be easier to understand by both human and 
machine. Machine understanding is important when transforming the GTK+ 
docs while trying to manipulate or filter out information like in/out 
parameters and memory ownership.

For example, for my language binding RGtk2, I produced R documentation 
from the GTK+ docs. RGtk2 hides memory management from the user and 
stuff like "out" parameters are handled very differently in R than in C. 
It would be nice if this information was included in a machine-readable 
way in the docs.

Thanks,
Michael Lawrence