Add type attribute for the free/unref function
Functions and methods that have full or container ownership transfer for return values and/or out
arguments typically add a doc snippet like: "call func
to free the returned data". This is not only a C-ism, which makes it harder to use the documentation in other languages, but it's also entirely unnecessary. We're already generating the text for the "transfer full" annotation: we can also generate a link to the free
function that is needed to free the data.
For that, we're going to need some help from the library itself. For object types, we can easily add g_object_unref()
ourselves; for GTypeInstance
types, we have access to the unref function from the introspection data; for integral types, we have g_free
; for list types, we have g_list_free
and g_slist_free
, for container transfer, and g_list_free_full
/g_slist_free_full
for full ownership transfer.
What's left are plain old data types (boxed or not); for those, we could add an attribute to the type that specified the free/unref function:
/**
* MyFoo: (attribute org.gtk.FreeFunc=my_foo_free)
*
* ...
*/
/**
* MyBar: (attribute org.gtk.FreeFunc=my_bar_unref)
*
* ...
*/
This would allow us to generate things like:
Ownership of the data is transferred to the caller. Use `{{ return_value.free_func }}` to free the resources associated with it.
Or, for a list of values:
Ownership of the data is transferred to the caller. Use `g_list_free_full()` and `{{ return_value.free_func }}` to free the resources associated with it.