diff --git a/kernel/hashlib.h b/kernel/hashlib.h
index 2d64c359a79..844e193ef73 100644
--- a/kernel/hashlib.h
+++ b/kernel/hashlib.h
@@ -21,6 +21,30 @@
 
 namespace hashlib {
 
+/**
+ * HASHING
+ *
+ * The Hasher knows how to hash basic stuff. Primitives and their
+ * common standard containers and compositions.
+ *
+ * The Hasher doesn't know how to hash silly Yosys-specific types.
+ * Hashlib doesn't depend on Yosys and can be used standalone.
+ * Please don't use hashlib standalone for new projects.
+ *
+ * The hash_ops type is now always left to its default value, derived
+ * from templated functions through SFINAE. Providing custom ops is
+ * still supported.
+ *
+ * HASH TABLES
+ *
+ * We implement associative data structures with separate chaining.
+ * Linked lists use integers into the indirection hashtable array
+ * instead of pointers.
+ */
+
+// TODO randomize iteration order for testing
+// TODO draw the line between generic and hash function specific code
+
 const int hashtable_size_trigger = 2;
 const int hashtable_size_factor = 3;
 
@@ -122,14 +146,14 @@ class Hasher {
 	struct hash_ops {
 		typedef hash_ops_impl<T, typename
 		std::conditional_t<
-        std::is_enum_v<T>,
-        enum_tag,
+		std::is_enum_v<T>,
+		enum_tag,
 
-        std::conditional_t<
+		std::conditional_t<
 		std::is_pointer_v<T>,
 		pointer_tag,
 
-        std::conditional_t<
+		std::conditional_t<
 		std::is_integral_v<T>,
 		integral_tag,
 
@@ -141,7 +165,7 @@ class Hasher {
 			return impl::cmp(a, b);
 		}
 	};
-// typename std::conditional<std::enable_if<std::is_integral<T>::value>, integral_tag, general_tag>::type{}
+
 	struct hash_int_ops {
 		template<typename T>
 		static inline bool cmp(T a, T b) {
@@ -156,7 +180,6 @@ class Hasher {
 		}
 	};
 
-	// TODO this isn't hash function agnostic
 	template<> struct hash_ops<uint32_t> : hash_int_ops
 	{
 		static inline Hasher hash_acc(uint32_t a, Hasher h) {
@@ -263,11 +286,6 @@ class Hasher {
 		}
 	};
 
-
-	// template<typename T>
-	// inline unsigned int mkhash(const T &v) {
-	// 	return hash_ops<T>().hash_acc(v);
-	// }
 };
 #endif