diff --git a/src/support/htable.h b/src/support/htable.h
index 317a9dae95e1d..3b52efabac8a1 100644
--- a/src/support/htable.h
+++ b/src/support/htable.h
@@ -6,11 +6,21 @@
 #define HT_N_INLINE 32
 
 #include "analyzer_annotations.h"
+#include <stddef.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+// Power-of-two hash table with linear probing.
+//
+// Keys and values are stored as in consecutive elements
+//   key   = table[2*i]
+//   value = table[2*i+1]
+// where `2*i < size`. An empty slot at index `i` is indicated with
+// `value == HT_NOTFOUND`.
+//
+// `_space` is reserved space for efficiently allocating small tables.
 typedef struct {
     size_t size;
     void **table;
@@ -20,13 +30,15 @@ typedef struct {
 // define this to be an invalid key/value
 #define HT_NOTFOUND ((void*)1)
 
-// initialize and free
+// initialize hash table, reserving space for `size` expected number of
+// elements. (Expect `h->size > size` for efficient occupancy factor.)
 htable_t *htable_new(htable_t *h, size_t size);
 void htable_free(htable_t *h);
 
 // clear and (possibly) change size
 void htable_reset(htable_t *h, size_t sz);
 
+// Lookup and mutation. See htable.inc for detail.
 #define HTPROT(HTNAME)                                                  \
 void *HTNAME##_get(htable_t *h, void *key) JL_NOTSAFEPOINT;             \
 void HTNAME##_put(htable_t *h, void *key, void *val) JL_NOTSAFEPOINT;   \