diff --git a/gobject/gobject.c b/gobject/gobject.c index 190ae19ec..3127d527c 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -83,7 +83,23 @@ * Since floating references are useful almost exclusively for C convenience, * language bindings that provide automated reference and memory ownership * maintenance (such as smart pointers or garbage collection) should not - * expose floating references in their API. + * expose floating references in their API. The best practice for handling + * types that have initially floating references is to immediately sink those + * references after g_object_new() returns, by checking if the #GType + * inherits from #GInitiallyUnowned. For instance: + * + * |[ + * GObject *res = g_object_new_with_properties (gtype, + * n_props, + * prop_names, + * prop_values); + * + * // or: if (g_type_is_a (gtype, G_TYPE_INITIALLY_UNOWNED)) + * if (G_IS_INITIALLY_UNOWNED (res)) + * g_object_ref_sink (res); + * + * return res; + * ]| * * Some object implementations may need to save an objects floating state * across certain code portions (an example is #GtkMenu), to achieve this,