diff --git a/src/hb-cache.hh b/src/hb-cache.hh
index 2e98187b5..8371465c6 100644
--- a/src/hb-cache.hh
+++ b/src/hb-cache.hh
@@ -30,7 +30,19 @@
 #include "hb.hh"
 
 
-/* Implements a lockfree cache for int->int functions. */
+/* Implements a lockfree cache for int->int functions.
+ *
+ * The cache is a fixed-size array of 16-bit or 32-bit integers.
+ * The key is split into two parts: the cache index and the rest.
+ *
+ * The cache index is used to index into the array.  The rest is used
+ * to store the key and the value.
+ *
+ * The value is stored in the least significant bits of the integer.
+ * The key is stored in the most significant bits of the integer.
+ * The key is shifted by cache_bits to the left to make room for the
+ * value.
+ */
 
 template <unsigned int key_bits=16,
 	 unsigned int value_bits=8 + 32 - key_bits,