diff --git a/esphome/core/event_pool.h b/esphome/core/event_pool.h
index 198c0fe380..7a206f823e 100644
--- a/esphome/core/event_pool.h
+++ b/esphome/core/event_pool.h
@@ -11,6 +11,8 @@ namespace esphome {
 
 // Event Pool - On-demand pool of objects to avoid heap fragmentation
 // Events are allocated on first use and reused thereafter, growing to peak usage
+// @tparam T The type of objects managed by the pool (must have a clear() method)
+// @tparam SIZE The maximum number of objects in the pool (1-255, limited by uint8_t)
 template<class T, uint8_t SIZE> class EventPool {
  public:
   EventPool() : total_created_(0) {}
@@ -71,7 +73,7 @@ template<class T, uint8_t SIZE> class EventPool {
 
  private:
   LockFreeQueue<T, SIZE> free_list_;  // Free events ready for reuse
-  uint8_t total_created_;             // Total events created (high water mark)
+  uint8_t total_created_;             // Total events created (high water mark, max 255)
 };
 
 }  // namespace esphome
diff --git a/esphome/core/lock_free_queue.h b/esphome/core/lock_free_queue.h
index 1fc5d25048..5460be0fae 100644
--- a/esphome/core/lock_free_queue.h
+++ b/esphome/core/lock_free_queue.h
@@ -24,6 +24,9 @@
  * Common use cases:
  * - BLE events: BLE task produces, main loop consumes
  * - MQTT messages: main task produces, MQTT thread consumes
+ *
+ * @tparam T The type of elements stored in the queue (must be a pointer type)
+ * @tparam SIZE The maximum number of elements (1-255, limited by uint8_t indices)
  */
 
 namespace esphome {
@@ -115,6 +118,8 @@ template<class T, uint8_t SIZE> class LockFreeQueue {
   // Atomic: written by producer (push/increment), read+reset by consumer (get_and_reset)
   std::atomic<uint16_t> dropped_count_;  // 65535 max - more than enough for drop tracking
   // Atomic: written by consumer (pop), read by producer (push) to check if full
+  // Using uint8_t limits queue size to 255 elements but saves memory and ensures
+  // atomic operations are efficient on all platforms
   std::atomic<uint8_t> head_;
   // Atomic: written by producer (push), read by consumer (pop) to check if empty
   std::atomic<uint8_t> tail_;