diff --git a/glib/ghash.c b/glib/ghash.c
index 02c0d7bdb..0ea372e74 100644
--- a/glib/ghash.c
+++ b/glib/ghash.c
@@ -145,12 +145,25 @@
  * hash functions which can be used when the key is a #gpointer, #gint,
  * and #gchar* respectively.
  *
- * <!-- 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
- * key into. The function should also be very fast, since it is called
- * for each key lookup.
- **/
+ * 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. --> A good hash functions should produce
+ * hash values that are 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 key into. The function should also
+ * be very fast, since it is called for each key lookup.
+ *
+ * Note that the hash functions provided by GLib have these qualities,
+ * but are not particularly robust against manufactured keys that
+ * cause hash collisions. Therefore, you should consider choosing
+ * a more secure hash function when using a GHashTable with keys
+ * that originate in untrusted data (such as HTTP requests).
+ * Using g_str_hash() in that situation might make your application
+ * vulerable to <ulink url="https://lwn.net/Articles/474912/">Algorithmic Complexity Attacks</ulink>.
+ *
+ * Returns: the hash value corresponding to the key
+ */
 
 /**
  * GHFunc: