From 34a122454966546fed0ccbb73338b28021e76481 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Tue, 4 Oct 2011 09:44:27 +0100 Subject: [PATCH] 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 Reviewed-by: Colin Walters --- glib/ghash.c | 20 ++++++++++++++------ 1 file 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 GINT_TO_POINTER (n). * * 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 GINT_TO_POINTER (n). * * Returns: %TRUE if the two keys match. */ -- 2.7.4