add header doc comments to non-obvious util data structures

debug_log/ring_buffer.h

@@ -3,6 +3,9 @@
 #include <cstdint>
 #include <span>
 
+// Fixed-capacity FIFO with wrap-around. push_overwrite drops the oldest entry
+// when full -- used by the debug log so dlog never blocks or fails. Iteration
+// walks logical positions head..tail, hiding the modular indexing.
 template <typename T, uint16_t N>
 struct ring_buffer {
     std::array<T, N> data = {};

include/callback_list.h

@@ -1,6 +1,9 @@
 #pragma once
 #include <utility>
 
+// Fixed-capacity doubly-linked list with an embedded node array and intrusive
+// free list. Used for callback registries (frame callbacks, timers) needing
+// O(1) insert/remove with stable handles, without heap in IRQ-adjacent paths.
 template <typename T, int N>
 struct callback_list {
     struct node {

include/parse_buffer.h

@@ -3,6 +3,9 @@
 #include <cstdint>
 #include <span>
 
+// Bounds-checked sequential reader for byte streams. consume<T>() returns a
+// typed pointer into the underlying buffer or nullptr on underflow. Used to
+// walk packet headers in order without UB and without copies.
 class parse_buffer {
     const uint8_t* m_data;
     size_t m_remaining;

include/prepend_buffer.h

@@ -4,6 +4,10 @@
 #include <cstring>
 #include <span>
 
+// Buffer that grows in both directions from a midpoint. Payload is appended at
+// the back; each protocol layer then prepends its header in reverse order
+// (UDP, then IPv4, then Ethernet) without moving payload bytes. Lets the
+// network stack build outbound frames bottom-up with no copies or scratch.
 template <size_t N>
 class prepend_buffer {
     uint8_t m_buf[N];

include/static_vector.h

@@ -3,6 +3,9 @@
 #include <cstdint>
 #include <cstring>
 
+// Fixed-capacity contiguous container: std::vector's interface with std::array's
+// storage. Used for response payloads sized at parse time but bounded at compile
+// time, where heap allocation is unavailable or undesirable.
 template <typename T, size_t Capacity>
 class static_vector {
     T m_data[Capacity];

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;

util/span_writer.h

@@ -4,6 +4,9 @@
 #include <cstring>
 #include <span>
 
+// Bounded writer over a caller-owned byte buffer. Tracks fill level and a
+// sticky overflow flag so packing code can write blindly and check once at the
+// end. Unlike std::span, it has a size cursor that grows toward capacity.
 class span_writer {
     uint8_t *m_data;
     size_t m_capacity;