[glib: 1/2] gobject: Clarify behaviour of adding weak refs during disposal

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 3b67d5322771544977d0f7c03ce7ad91af946874
Author: Philip Withnall <pwithnall endlessos org>
Date:   Mon Sep 20 13:18:03 2021 +0100

    gobject: Clarify behaviour of adding weak refs during disposal
    
    The previous wording was not clear about what happens if a new weak ref
    is taken during disposal (shortly after resurrecting the object with a
    new strong ref, otherwise taking the weak ref is invalid).
    
    See: https://gitlab.gnome.org/GNOME/glib/-/merge_requests/2064/diffs#note_1270092
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>
    
    Helps: #2390

 gobject/gobject.c | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)
---
diff --git a/gobject/gobject.c b/gobject/gobject.c
index 9776d7c95..90d0f17d6 100644
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -4552,11 +4552,14 @@ g_initially_unowned_class_init (GInitiallyUnownedClass *klass)
  * objects.
  *
  * If the object's #GObjectClass.dispose method results in additional
- * references to the object being held, any #GWeakRefs taken
- * before it was disposed will continue to point to %NULL.  If
- * #GWeakRefs are taken after the object is disposed and
- * re-referenced, they will continue to point to it until its refcount
+ * references to the object being held (‘re-referencing’), any #GWeakRefs taken
+ * before it was disposed will continue to point to %NULL.  Any #GWeakRefs taken
+ * during disposal and after re-referencing, or after disposal has returned due
+ * to the re-referencing, will continue to point to the object until its refcount
  * goes back to zero, at which point they too will be invalidated.
+ *
+ * It is invalid to take a #GWeakRef on an object during #GObjectClass.dispose
+ * without first having or creating a strong reference to the object.
  */
 
 /**