Add some smarts to indicate in generated docs functions which return floating references
Today I was wondering whether gtk_list_store_new()
returns a floating reference or not. My conclusion is that it would be better to indicate this as part of the documentation block generated for a function.The rationale is:
- For people who know that anything that inherits from
GInitiallyUnowned
results in a floating reference on instantiation it can be obvious, but I wasn't aware of that and I have used GLib/GTK+ for years. - Even if one knows about
GInitiallyUnowned
, when checking the documentation for function one needs to jump over to the “Object Hierarchy” section (and possibly back to the function documentation right after). - The documentation for
GInitiallyUnowned
, where it's stated that inheriting from it results in a floating reference, it's buried in the middle the very long documentation page forGObject
, which means poor discoverability. - Moreover, even if a class does not inherit from
GInitiallyUnowned
, a function which returns a new instance could have calledg_object_force_floating()
(o vice versa).
On IRC @ebassi mentioned that there is already a (transfer floating)
annotation which is used e.g. for things that do not inherit from GInitiallyUnowned
, or are not derived from GObject
but use floating references (like GVariant
).
All in all, gtk-doc
already has some information about this, either via the (transfer floating)
annotation or because it knows that a certain class inherits from GInitiallyUnowned
, and it seems to me like it would be a good thing to automatically generate some note in the documentation that a function returns a floating reference to avoid users of our libraries to do guesswork to know which kind of reference they are getting from a function.