[glib] GHashTable: be more clear what g_int_hash wants

[Simon McVittie <smcv src gnome org>]

commit 06c96ab1e59dead8a920433498624b946abdb9ab
Author: Simon McVittie <simon mcvittie collabora co uk>
Date:   Tue Oct 4 09:42:28 2011 +0100

    GHashTable: be more clear what g_int_hash wants
    
    Using g_int_hash, g_int_equal with keys like GINT_TO_POINTER (n) seems to
    be a reasonably common GLib-novice mistake. It doesn't help that the
    documentation for GHashFunc was ambiguous about this.
    
    Bug: https://bugzilla.gnome.org/show_bug.cgi?id=592715
    Signed-off-by: Simon McVittie <simon mcvittie collabora co uk>
    Reviewed-by: Colin Walters <walters verbum org>

 glib/ghash.c |   13 ++++++++++++-
 1 files changed, 12 insertions(+), 1 deletions(-)
---
diff --git a/glib/ghash.c b/glib/ghash.c
index c7a9778..6294ddc 100644
--- a/glib/ghash.c
+++ b/glib/ghash.c
@@ -142,9 +142,12 @@
  *
  * The function is passed a key and should return a #guint hash value.
  * The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
- * hash functions which can be used when the key is a #gpointer, #gint,
+ * hash functions which can be used when the key is a #gpointer, #gint*,
  * and #gchar* respectively.
  *
+ * g_direct_hash() is also the appropriate hash function for keys
+ * of the form <literal>GINT_TO_POINTER (n)</literal> (or similar macros).
+ *
  * <!-- FIXME: Need more here. --> The hash values should be evenly
  * distributed over a fairly large range? The modulus is taken with the
  * hash table size (a prime number) to find the 'bucket' to place each
@@ -1697,6 +1700,10 @@ g_direct_equal (gconstpointer v1,
  * It can be passed to g_hash_table_new() as the @key_equal_func
  * parameter, when using pointers to integers as keys in a #HashTable.
  *
+ * Note that this function acts on pointers to #gint, not on #gint directly:
+ * if your hash table's keys are of the form
+ * <literal>GINT_TO_POINTER (n)</literal>, use g_direct_equal() instead.
+ *
  * Returns: %TRUE if the two keys match.
  */
 gboolean
@@ -1714,6 +1721,10 @@ g_int_equal (gconstpointer v1,
  * It can be passed to g_hash_table_new() as the @hash_func parameter,
  * when using pointers to integers values as keys in a #GHashTable.
  *
+ * Note that this function acts on pointers to #gint, not on #gint directly:
+ * if your hash table's keys are of the form
+ * <literal>GINT_TO_POINTER (n)</literal>, use g_direct_hash() instead.
+ *
  * Returns: a hash value corresponding to the key.
  */
 guint