[glib: 1/2] ghash: Clarify that g_hash_table_add() always consumes the key

[Philip Withnall <pwithnall src gnome org>]

commit b52bb753273ad2b1064e142b4ce2aebbce85fb3b
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Jan 31 12:13:23 2020 +0000

    ghash: Clarify that g_hash_table_add() always consumes the key
    
    Even if the key already exists in the table, `g_hash_table_add()` will
    call the hash table’s key free func on the old key and will then replace
    the old key with the newly-passed-in key. So `key` is always `(transfer
    full)`.
    
    In particular, `key` should never need to be freed by the caller if
    `g_hash_table_add()` returns `FALSE`.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 glib/ghash.c | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)
---
diff --git a/glib/ghash.c b/glib/ghash.c
index 171011b39..549baa9ea 100644
--- a/glib/ghash.c
+++ b/glib/ghash.c
@@ -1651,12 +1651,16 @@ g_hash_table_replace (GHashTable *hash_table,
 /**
  * g_hash_table_add:
  * @hash_table: a #GHashTable
- * @key: a key to insert
+ * @key: (transfer full): a key to insert
  *
  * This is a convenience function for using a #GHashTable as a set.  It
  * is equivalent to calling g_hash_table_replace() with @key as both the
  * key and the value.
  *
+ * In particular, this means that if @key already exists in the hash table, then
+ * the old copy of @key in the hash table is freed and @key replaces it in the
+ * table.
+ *
  * When a hash table only ever contains keys that have themselves as the
  * corresponding value it is able to be stored more efficiently.  See
  * the discussion in the section description.