[socket] Address review comments: doc comments and (void) flags

- Document port_host byte order convention in lwip_ip_to_sockaddr
- Note intentional method hiding in LWIPRawUDPRecvImpl
- Note recvfrom truncation differs from POSIX MSG_TRUNC
- Add (void) flags in sendto to clarify flags are ignored

Co-Authored-By: J. Nick Koston <nick@koston.org>

esphome/components/socket/lwip_raw_tcp_impl.cpp

@@ -145,6 +145,9 @@ static const char *const TAG = "socket.lwip";
 // ---- Shared helpers ----
 
 /// Convert lwip ip_addr_t + host-order port to sockaddr, based on the socket's address family.
+/// @param port_host Port in host byte order. TCP callers must convert from network order first
+///                  (tcp_pcb stores ports in network byte order); UDP callers can pass directly
+///                  (lwip udp_recv callback provides port in host byte order).
 /// Shared by both TCP (LWIPRawCommon) and UDP (LWIPRawUDPImpl) implementations.
 static int lwip_ip_to_sockaddr(sa_family_t family, const ip_addr_t *ip, uint16_t port_host, struct sockaddr *name,
                                socklen_t *addrlen) {
@@ -895,6 +898,7 @@ int LWIPRawUDPImpl::ip2sockaddr_(const ip_addr_t *ip, uint16_t port, struct sock
 
 ssize_t LWIPRawUDPImpl::sendto(const void *buf, size_t len, int flags, const struct sockaddr *dest_addr,
                                socklen_t addrlen) {
+  (void) flags;  // Flags (MSG_DONTWAIT, etc.) are ignored; raw lwip is always non-blocking
   if (this->pcb_ == nullptr) {
     errno = EBADF;
     return -1;

esphome/components/socket/lwip_raw_tcp_impl.h

@@ -243,6 +243,11 @@ class LWIPRawUDPImpl {
 /// UDP socket with receive support for LWIP raw API.
 /// Extends LWIPRawUDPImpl with a fixed-size ring buffer for incoming packets.
 /// The recv callback is registered on bind().
+///
+/// Note: close() and bind() intentionally hide the base class methods to add
+/// recv callback registration/cleanup. This is safe because these classes are
+/// never used polymorphically (no virtual dispatch) — callers always use the
+/// concrete LWIPRawUDPRecvImpl type via the UDPRecvSocket alias.
 class LWIPRawUDPRecvImpl : public LWIPRawUDPImpl {
  public:
   using LWIPRawUDPImpl::LWIPRawUDPImpl;
@@ -256,9 +261,11 @@ class LWIPRawUDPRecvImpl : public LWIPRawUDPImpl {
 
   /// Read the next queued packet, discarding source address info.
   /// If buf is smaller than the packet, data is silently truncated (returns bytes copied).
+  /// Note: unlike POSIX MSG_TRUNC, this does not return the original packet length on truncation.
   ssize_t read(void *buf, size_t len);
   /// Read the next queued packet and return the source address.
   /// If buf is smaller than the packet, data is silently truncated (returns bytes copied).
+  /// Note: unlike POSIX MSG_TRUNC, this does not return the original packet length on truncation.
   ssize_t recvfrom(void *buf, size_t len, struct sockaddr *src_addr, socklen_t *addrlen);
 
   /// Returns true if there are packets available to read.