[glib: 1/2] refcount: Clarify when the ref count ends up undefined

[Philip Withnall <pwithnall src gnome org>]

commit 21cc809158bfe8fd4efc7292b7ab13288a385b73
Author: Jonas Ådahl <jadahl gmail com>
Date:   Fri Apr 9 11:13:36 2021 +0200

    refcount: Clarify when the ref count ends up undefined
    
    Calling g_atomic_ref_count_dec() or g_ref_count_dec() and the reference
    count reaches zero results in different side effects depending on
    whether the reference count is atomic or not.
    
    The intended side effect when this happens is undefined, i.e. one should
    not rely on the reference count actually reaching zero, or staying 1, or
    becoming something else, and one should treat the grefcount /
    gatomicrefcount to be unusable until reinitialized.
    
    This wasn't documented, so add a paragraph about this.

 glib/grefcount.c | 8 ++++++++
 1 file changed, 8 insertions(+)
---
diff --git a/glib/grefcount.c b/glib/grefcount.c
index 7cb12fc46..9dae60ad8 100644
--- a/glib/grefcount.c
+++ b/glib/grefcount.c
@@ -142,6 +142,10 @@ void
  *
  * Decreases the reference count.
  *
+ * If %TRUE is returned, the reference count reached 0. After this point, @rc
+ * is an undefined state and must be reinitialized with
+ * g_ref_count_init() to be used again.
+ *
  * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise
  *
  * Since: 2.58
@@ -249,6 +253,10 @@ void
  *
  * Atomically decreases the reference count.
  *
+ * If %TRUE is returned, the reference count reached 0. After this point, @arc
+ * is an undefined state and must be reinitialized with
+ * g_atomic_ref_count_init() to be used again.
+ *
  * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise
  *
  * Since: 2.58