gobject introspection and gtk-doc


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.

Michael Lawrence

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