Making the life of the wrappers maintainers easier

[Guillaume Laurent <glaurent worldnet fr>]

One of the big arguments of GTK+ and Gnome is that, being in C, they
should be easy to wrap to other languages.

While this is true in principle, there are many factors which can
render this process very tedious.

Here are a few tips and requests which would greatly help us. Of
course this is written from a C++ perspective. But while this
language, and Gtk-- itself, have issues of their own, I'm pretty
confident the developers of other language bindings would agree with
these advices.

The basic idea is, we'd like to have everything we need to know in one
place only (that is, the header file). Having to look into the source
to check for some ambiguity often amounts to a shot in the dark. So
here goes :

 - An old Gtk-- specific issue : if a widget needs complex operations
   at construction (anything beyond gtk_type_new() and returning the
   result), we need a seperate gtk_*_configure() call (see
   GtkSpinButton or GtkMenuItem for instance). A bad example of this is the
   GnomeMessageBox, which can't be wrapped yet because of this.

 - Clearly specify what is for the user and what is private or
   internal. This mostly means data fields, signals and sometimes
   functions (in the rare case a function is exported to be used by
   other widgets but not the user). A nice example of is
   gtkeditable.h, a bad one is gtkspinbutton.h.

 - More specifically about signals : specify if the user can connect
   them, or call them directly.

 - When returning a pointer, specify if it's up to the user to free it
   or not, and if it's const or not. Also, make sure there are no
   doubts as to whether the pointer is actually an array (such cases
   of ambiguity are rare, though).

Thank you for your kind attention, now back to our regularly scheduled 
hacking:-).

-- 
					Guillaume.
					http://home.worldnet.fr/~glaurent