Glib::Binding: Clarify need to hold ref, poss empty objs

and move the documentation on lifetime away from bind_property_value()
up to the class description/intro.

https://gitlab.gnome.org/GNOME/glibmm/issues/62

1 files changed, 9 insertions, 10 deletions

diff --git a/glib/src/binding.hg b/glib/src/binding.hg
index 80f8f3f1..4ad909d8 100644
--- a/glib/src/binding.hg
+++ b/glib/src/binding.hg
@@ -28,7 +28,7 @@ _WRAP_ENUM(BindingFlags, GBindingFlags, newin "2,44", decl_prefix GLIBMM_API)
 
 /** Bind two object properties.
  *
- * Glib::Binding is the representation of a binding between a property on a
+ * %Glib::Binding is the representation of a binding between a property on a
  * Glib::ObjectBase instance (or source) and another property on another Glib::ObjectBase
  * instance (or target). Whenever the source property changes, the same
  * value is applied to the target property; for instance, the following binding:
@@ -74,7 +74,7 @@ _WRAP_ENUM(BindingFlags, GBindingFlags, newin "2,44", decl_prefix GLIBMM_API)
  * current value of the property before applying it to property_value()
  * of @a adjustment1.
  *
- * Note that Glib::Binding does not resolve cycles by itself; a cycle like
+ * Note that %Glib::Binding does not resolve cycles by itself; a cycle like
  *
  * @code
  *   object1->property_A() -> object2->property_B()
@@ -89,10 +89,13 @@ _WRAP_ENUM(BindingFlags, GBindingFlags, newin "2,44", decl_prefix GLIBMM_API)
  * various ways of blocking a signal emission, like Glib::SignalProxyNormal::emission_stop()
  * or g_signal_handler_block().
  *
- * A binding will be severed, and the resources it allocates freed, whenever
- * either one of the Glib::ObjectBase instances it refers to is deleted,
- * when unbind() is called, or when the Glib::Binding instance loses
- * its last reference.
+ * The binding between properties is broken, and its resources freed, when the
+ * %Glib::Binding loses its last Glib::RefPtr, the source or target object is
+ * deleted, or unbind() is called. If a Glib::RefPtr to the %Glib::Binding
+ * remains after the binding is broken another way, get_source()
+ * and get_target() return an empty Glib::RefPtr. So, you must
+ * keep a Glib::RefPtr to the %Glib::Binding for as long as you want it to bind,
+ * but doing that does not guarantee the source/target are still alive or bound.
  *
  * @newin{2,44}
  */
@@ -144,10 +147,6 @@ public:
    * will be updated as well. The @a transform_from function is only used in case
    * of bidirectional bindings, otherwise it will be ignored.
    *
-   * The binding will automatically be removed when either the source or the
-   * target instance is deleted. To remove the binding without affecting the
-   * source and the target you can call unbind() on the returned Binding instance.
-   *
    * A Glib::ObjectBase instance can have multiple bindings.
    *
    * If you supply transformation functions, it is usually easier to use one of the