[glib] gobject: Mention g_clear_object() in g_object_unref() documentation

[Philip Withnall <pwithnall src gnome org>]

commit 4aedc85fb35f58b602259d34b94dcebeefa198bc
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Fri Dec 19 19:02:15 2014 +0000

    gobject: Mention g_clear_object() in g_object_unref() documentation
    
    https://bugzilla.gnome.org/show_bug.cgi?id=741779

 gobject/gobject.c |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)
---
diff --git a/gobject/gobject.c b/gobject/gobject.c
index 4a8d032..ae6265e 100644
--- 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)