gobject: Mention g_clear_object() in g_object_unref() documentation

https://bugzilla.gnome.org/show_bug.cgi?id=741779

diff --git a/gobject/gobject.c b/gobject/gobject.c
index 4a8d032..ae6265e 100644 (file)
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -3057,6 +3057,11 @@ g_object_ref (gpointer _object)
  *
  * Decreases the reference count of @object. When its reference count
  * drops to 0, the object is finalized (i.e. its memory is freed).
+ *
+ * If the pointer to the #GObject may be reused in future (for example, if it is
+ * an instance variable of another object), it is recommended to clear the
+ * pointer to %NULL rather than retain a dangling pointer to a potentially
+ * invalid #GObject instance. Use g_clear_object() for this.
  */
 void
 g_object_unref (gpointer _object)