[api] Trim verbose comments in include refactor

esphome/components/api/api_connection.cpp

@@ -1,8 +1,6 @@
 #include "api_connection.h"
 #ifdef USE_API
-// Pulls in api_server.h (APIServer complete) and the inline encode_to_buffer
-// and get_batch_delay_ms_ definitions that need it.
-#include "api_connection_buffer.h"
+#include "api_connection_buffer.h"  // for encode_to_buffer / get_batch_delay_ms_ inlines
 #ifdef USE_API_NOISE
 #include "api_frame_helper_noise.h"
 #endif

esphome/components/api/api_connection.h

@@ -37,9 +37,7 @@ class ComponentIterator;
 
 namespace esphome::api {
 
-// Forward declaration to break the api_connection.h <-> api_server.h include cycle.
-// APIServer is only used through pointers/references in this header; the few
-// inline methods that need the complete type are defined in api_connection_buffer.h.
+// Forward-declared to break the api_server.h cycle; full-type inlines are in api_connection_buffer.h.
 class APIServer;
 
 // Keepalive timeout in milliseconds
@@ -417,11 +415,8 @@ class APIConnection final : public APIServerConnectionBase {
   // Non-template buffer management for send_message
   bool send_message_(uint32_t payload_size, uint8_t message_type, MessageEncodeFn encode_fn, const void *msg);
 
-  // Core batch encoding logic. Computes header size, checks fit, resizes buffer, encodes.
-  // ALWAYS_INLINE so the compiler can devirtualize encode_fn at hot call sites.
-  // Definition lives in api_connection_buffer.h, where APIServer is a complete type
-  // (needed for conn->parent_->get_shared_buffer_ref()). Callers must include
-  // api_connection_buffer.h.
+  // Core batch encoding logic. ALWAYS_INLINE so encode_fn devirtualizes at hot call sites.
+  // Defined in api_connection_buffer.h (needs APIServer complete).
   static uint16_t ESPHOME_ALWAYS_INLINE encode_to_buffer(uint32_t calculated_size, MessageEncodeFn encode_fn,
                                                          const void *msg, APIConnection *conn, uint32_t remaining_size);
 
@@ -767,7 +762,7 @@ class APIConnection final : public APIServerConnectionBase {
   // Read by process_batch_multi_ to pass into MessageInfo.
   uint8_t batch_header_size_{0};
 
-  // Definition in api_connection_buffer.h (needs APIServer complete).
+  // Defined in api_connection_buffer.h (needs APIServer complete).
   uint32_t get_batch_delay_ms_() const;
   // Message will use 8 more bytes than the minimum size, and typical
   // MTU is 1500. Sometimes users will see as low as 1460 MTU.

esphome/components/api/api_connection_buffer.h

@@ -3,15 +3,8 @@
 #include "esphome/core/defines.h"
 #ifdef USE_API
 
-// Inline definitions for APIConnection members that need the complete
-// APIServer type (currently encode_to_buffer for the hot batch-send path and
-// get_batch_delay_ms_). Pulled into a dedicated header so api_server.h does
-// not have to carry APIConnection method bodies and api_connection.h can
-// keep just a forward declaration of APIServer, breaking the include cycle
-// that previously forced a custom std::unique_ptr deleter on libc++.
-//
-// Include this header from translation units that call encode_to_buffer or
-// any other APIConnection inline that touches APIServer.
+// Inline APIConnection methods that need APIServer complete. Include this
+// instead of api_connection.h when calling encode_to_buffer or get_batch_delay_ms_.
 
 #include "api_connection.h"
 #include "api_server.h"

esphome/components/api/api_server.h

@@ -3,11 +3,7 @@
 #include "esphome/core/defines.h"
 #ifdef USE_API
 #include "api_buffer.h"
-// api_connection.h must be included before clients_ is declared so APIConnection
-// is a complete type when std::unique_ptr<APIConnection> is instantiated. libc++
-// otherwise trips static_assert(sizeof(_Tp) >= 0, "cannot delete an incomplete
-// type") while parsing the array member. api_connection.h transitively brings in
-// list_entities.h and subscribe_state.h.
+// Must precede clients_ so APIConnection is complete for default_delete (libc++).
 #include "api_connection.h"
 #include "api_noise_context.h"
 #include "api_pb2.h"