[glib/floating-ref-warning: 31/32] Document the best practice for binding InitiallyUnowned

[Emmanuele Bassi <ebassi src gnome org>]

commit a734a92408494e4637ff6404bd515d15618f1f8d
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sun May 12 17:06:51 2019 +0100

    Document the best practice for binding InitiallyUnowned
    
    Right now, the documentation is less than explicit on how language
    bindings should handle GInitiallyUnowned.

 gobject/gobject.c | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)
---
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:
+ *
+ * |[<!-- language="C" -->
+ * 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,