[glib/th/hash-steal-doc: 10/10] ghash: comment g_hash_table_steal_extended() about not destroying key/value

[Thomas Haller <thaller src gnome org>]

commit 1038b19788535abdfbced36efb3f9a84057f8545
Author: Thomas Haller <thaller redhat com>
Date:   Fri Oct 14 12:49:21 2022 +0200

    ghash: comment g_hash_table_steal_extended() about not destroying key/value
    
    The previous text was technically correct, but not very clear what
    happens with the ownership of the key/value if it was not returned.
    Elaborate on the fact, that the key/value is never destroyed, even if
    not requested by the user.
    
    I intuitively expected the function to behave differently, that is, to
    destroy the key/value if (and only if) it was not returned. That is,
    when the function does not return a pointer, then it would destroy it.
    That would seem more consistent to me, where ownership is either
    transferred to the caller, or the resource destroyed during the steal.
    
    On the other hand, the existing behaviors is:
    
    - is consistent with g_hash_table_steal() and never destroys key/value.
    - behaves the same, regardless whether the key/value was returned.
    
    So the existing behavior may be better.
    
    Just elaborate on that detail in the doc.

 glib/ghash.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
---
diff --git a/glib/ghash.c b/glib/ghash.c
index 0e6ba4882c..366c751acc 100644
--- a/glib/ghash.c
+++ b/glib/ghash.c
@@ -1834,7 +1834,9 @@ g_hash_table_steal (GHashTable    *hash_table,
  *
  * If found, the stolen key and value are removed from the hash table without
  * calling the key and value destroy functions, and ownership is transferred to
- * the caller of this method; as with g_hash_table_steal().
+ * the caller of this method, as with g_hash_table_steal(). That is the case
+ * regardless whether @stolen_key or @stolen_value output parameters are
+ * requested.
  *
  * You can pass %NULL for @lookup_key, provided the hash and equal functions
  * of @hash_table are %NULL-safe.