[glib/th/ghash-steal-extended-doc] ghash: document g_hash_table_steal_extended() behavior for sets

[Thomas Haller <thaller src gnome org>]

commit 80f871074f7ae3d110ec5cc5f30674b58886b36b
Author: Thomas Haller <thaller redhat com>
Date:   Thu Oct 13 22:47:29 2022 +0200

    ghash: document g_hash_table_steal_extended() behavior for sets
    
    GHashTable is optimized for using g_hash_table_add(), where the
    key and the value are identical.
    
    When using g_hash_table_steal_extended() on such a dictionary,
    and requesting both a key and a value, then the stolen value will be
    NULL.
    
    That would be easy to fix, but it also would be an API break.
    Instead, document this behavior.

 glib/ghash.c | 4 ++++
 1 file changed, 4 insertions(+)
---
diff --git a/glib/ghash.c b/glib/ghash.c
index 808ec628aa..77bd2ff5f1 100644
--- a/glib/ghash.c
+++ b/glib/ghash.c
@@ -1839,6 +1839,10 @@ g_hash_table_steal (GHashTable    *hash_table,
  * You can pass %NULL for @lookup_key, provided the hash and equal functions
  * of @hash_table are %NULL-safe.
  *
+ * The dictionary implementation optimizes for having all values identical to their keys,
+ * for example by using g_hash_table_add(). When stealing both the key and the value
+ * from such a dictionary, the value will be %NULL.
+ *
  * Returns: %TRUE if the key was found in the #GHashTable
  * Since: 2.58
  */