add header doc comments to non-obvious util data structures

include/timer_queue.h

@@ -9,6 +9,9 @@ struct timer_entry {
 
 using timer_handle = callback_list<timer_entry, 16>::node*;
 
+// Deadline-sorted callback list with a single hardware alarm armed at the
+// head. The alarm IRQ sets a flag; run() drains expired entries on the main
+// loop, so callbacks execute in normal context rather than interrupt context.
 struct timer_queue {
     callback_list<timer_entry, 16> list;
     alarm_id_t alarm = -1;