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
GInitiallyUnownedresults 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 for
GObject, which means poor discoverability.
- Moreover, even if a class does not inherit from
GInitiallyUnowned, a function which returns a new instance could have called
g_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
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.