fun project!

[Havoc Pennington <hp redhat com>]

Hi,

The GTK+ sources need to be marked up with magic comments describing
certain parameters and return values, for the benefit of language
bindings. Most commonly:

 - whether returned values do/don't need to be freed
 - whether returned values or parameters can be NULL

Magic comments should only be added for non-standard
behavior. Standard behavior is:
 - arguments can't be NULL
 - return values can't be NULL
 - returned strings must be freed
 - returned GtkObject should not be unreferenced

Some proposed magic comments after talking to Owen briefly:

 - /*< nofree >*/      a return value or arg not to free
 - /*< mustfree >*/    one you have to free
 - /*< nullok >*/      something that can be NULL
 - /*< nonull >*/      something that can't

Combine options with comma:
 /*< nofree, nullok >*/

Examples:
 
/*< nofree >*/
gchar * gtk_type_name (GtkType type);

void gtk_tooltips_set_tip (GtkTooltips *tips,
                           GtkWidget   *widget,
                           const gchar *text,           /*< nullok >*/
                           const gchar *text_private);  /*< nullok >*/



Anyway, any volunteers out there to do this? The most pressing need is
probably 'gchar*' return values; other stuff can wait.

Havoc