[glib] Be completely clear about what g_direct_hash, g_direct_equal do

[Simon McVittie <smcv src gnome org>]

commit 34a122454966546fed0ccbb73338b28021e76481
Author: Simon McVittie <simon mcvittie collabora co uk>
Date:   Tue Oct 4 09:44:27 2011 +0100

    Be completely clear about what g_direct_hash, g_direct_equal do
    
    Also annotate them as (allow-none), more for the benefit of gtk-doc
    readers than introspection.
    
    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 |   20 ++++++++++++++------
 1 files changed, 14 insertions(+), 6 deletions(-)
---
diff --git a/glib/ghash.c b/glib/ghash.c
index 6294ddc..68e75c0 100644
--- a/glib/ghash.c
+++ b/glib/ghash.c
@@ -1658,11 +1658,15 @@ g_str_hash (gconstpointer v)
 
 /**
  * g_direct_hash:
- * @v: a #gpointer key
+ * @v: (allow-none): a #gpointer key
  *
  * Converts a gpointer to a hash value.
- * It can be passed to g_hash_table_new() as the @hash_func parameter, 
- * when using pointers as keys in a #GHashTable.
+ * It can be passed to g_hash_table_new() as the @hash_func parameter,
+ * when using opaque pointers compared by pointer value as keys in a
+ * #GHashTable.
+ *
+ * This hash function is also appropriate for keys that are integers stored
+ * in pointers, such as <literal>GINT_TO_POINTER (n)</literal>.
  *
  * Returns: a hash value corresponding to the key.
  */
@@ -1674,12 +1678,16 @@ g_direct_hash (gconstpointer v)
 
 /**
  * g_direct_equal:
- * @v1: a key
- * @v2: a key to compare with @v1
+ * @v1: (allow-none): a key
+ * @v2: (allow-none): a key to compare with @v1
  *
  * Compares two #gpointer arguments and returns %TRUE if they are equal.
  * It can be passed to g_hash_table_new() as the @key_equal_func
- * parameter, when using pointers as keys in a #GHashTable.
+ * parameter, when using opaque pointers compared by pointer value as keys
+ * in a #GHashTable.
+ *
+ * This equality function is also appropriate for keys that are integers stored
+ * in pointers, such as <literal>GINT_TO_POINTER (n)</literal>.
  *
  * Returns: %TRUE if the two keys match.
  */