[glib: 1/2] binding: Clarify the use of g_object_unref() to remove a binding

[Philip Withnall <pwithnall src gnome org>]

commit f5e1e169d0adfdb5121dca53e2c576b1309095ce
Author: Benjamin Berg <bberg redhat com>
Date:   Thu Dec 6 12:26:39 2018 +0100

    binding: Clarify the use of g_object_unref() to remove a binding
    
    Conceptually the binding is kept alive as long as both the source and
    target exist. This means that an API user needs to take some care to
    either hold a reference or only use a pointer to the binding as long as
    also holding references to both objects.
    
    Clarify the documentation a bit.

 gobject/gbinding.c | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)
---
diff --git a/gobject/gbinding.c b/gobject/gbinding.c
index 42dcb366f..16942c221 100644
--- a/gobject/gbinding.c
+++ b/gobject/gbinding.c
@@ -799,9 +799,11 @@ g_binding_unbind (GBinding *binding)
  * of bidirectional bindings, otherwise it will be ignored
  *
  * The binding will automatically be removed when either the @source or the
- * @target instances are finalized. To remove the binding without affecting the
- * @source and the @target you can just call g_object_unref() on the returned
- * #GBinding instance.
+ * @target instances are finalized. This will release the reference that is
+ * being held on the #GBinding instance; if you want to hold on to the
+ * #GBinding instance, you will need to hold a reference to it.
+ *
+ * To remove the binding, call g_binding_unbind().
  *
  * A #GObject can have multiple bindings.
  *