From abb1c62ff7e45ea4834f101a3dcef9962ab3c32f Mon Sep 17 00:00:00 2001
From: Peter Limkilde Svendsen <peter.limkilde@proton.me>
Date: Wed, 8 Apr 2026 23:24:50 +0200
Subject: [PATCH] Add docs for PalSocket

---
 src/platform/pal/socket.rs | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/src/platform/pal/socket.rs b/src/platform/pal/socket.rs
index 77c970deff..9d2c29ffbb 100644
--- a/src/platform/pal/socket.rs
+++ b/src/platform/pal/socket.rs
@@ -10,33 +10,40 @@ use crate::{
     },
 };
 
+/// Platform abstraction of socket functionality.
 pub trait PalSocket: Pal {
+    /// Platform implementation of [`accept()`](crate::header::sys_socket::accept) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn accept(
         socket: c_int,
         address: *mut sockaddr,
         address_len: *mut socklen_t,
     ) -> Result<c_int>;
 
+    /// Platform implementation of [`bind()`](crate::header::sys_socket::bind) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn bind(socket: c_int, address: *const sockaddr, address_len: socklen_t) -> Result<()>;
 
+    /// Platform implementation of [`connect()`](crate::header::sys_socket::connect) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn connect(
         socket: c_int,
         address: *const sockaddr,
         address_len: socklen_t,
     ) -> Result<c_int>;
 
+    /// Platform implementation of [`getpeername()`](crate::header::sys_socket::getpeername) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn getpeername(
         socket: c_int,
         address: *mut sockaddr,
         address_len: *mut socklen_t,
     ) -> Result<()>;
 
+    /// Platform implementation of [`getsockname()`](crate::header::sys_socket::getsockname) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn getsockname(
         socket: c_int,
         address: *mut sockaddr,
         address_len: *mut socklen_t,
     ) -> Result<()>;
 
+    /// Platform implementation of [`getsockopt()`](crate::header::sys_socket::getsockopt) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn getsockopt(
         socket: c_int,
         level: c_int,
@@ -45,8 +52,10 @@ pub trait PalSocket: Pal {
         option_len: *mut socklen_t,
     ) -> Result<()>;
 
+    /// Platform implementation of [`listen()`](crate::header::sys_socket::listen) from [`sys/socket.h`](crate::header::sys_socket).
     fn listen(socket: c_int, backlog: c_int) -> Result<()>;
 
+    /// Platform implementation of [`recvfrom()`](crate::header::sys_socket::recvfrom) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn recvfrom(
         socket: c_int,
         buf: *mut c_void,
@@ -56,10 +65,13 @@ pub trait PalSocket: Pal {
         address_len: *mut socklen_t,
     ) -> Result<usize>;
 
+    /// Platform implementation of [`recvmsg()`](crate::header::sys_socket::recvmsg) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn recvmsg(socket: c_int, msg: *mut msghdr, flags: c_int) -> Result<usize>;
 
+    /// Platform implementation of [`sendmsg()`](crate::header::sys_socket::sendmsg) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn sendmsg(socket: c_int, msg: *const msghdr, flags: c_int) -> Result<usize>;
 
+    /// Platform implementation of [`sendto()`](crate::header::sys_socket::sendto) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn sendto(
         socket: c_int,
         buf: *const c_void,
@@ -69,6 +81,7 @@ pub trait PalSocket: Pal {
         dest_len: socklen_t,
     ) -> Result<usize>;
 
+    /// Platform implementation of [`setsockopt()`](crate::header::sys_socket::setsockopt) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn setsockopt(
         socket: c_int,
         level: c_int,
@@ -77,9 +90,12 @@ pub trait PalSocket: Pal {
         option_len: socklen_t,
     ) -> Result<()>;
 
+    /// Platform implementation of [`shutdown()`](crate::header::sys_socket::shutdown) from [`sys/socket.h`](crate::header::sys_socket).
     fn shutdown(socket: c_int, how: c_int) -> Result<()>;
 
+    /// Platform implementation of [`socket()`](crate::header::sys_socket::socket) from [`sys/socket.h`](crate::header::sys_socket).
     unsafe fn socket(domain: c_int, kind: c_int, protocol: c_int) -> Result<c_int>;
 
+    /// Platform implementation of [`socketpair()`](crate::header::sys_socket::socketpair) from [`sys/socket.h`](crate::header::sys_socket).
     fn socketpair(domain: c_int, kind: c_int, protocol: c_int, sv: &mut [c_int; 2]) -> Result<()>;
 }