From 8806494899b5db6b83168c25f518b8236b3748f1 Mon Sep 17 00:00:00 2001
From: Paul Spooren <mail@aparcar.org>
Date: Wed, 6 Nov 2024 17:21:02 +0100
Subject: [PATCH] docs(mio): fix docstring warnings

Signed-off-by: Paul Spooren <mail@aparcar.org>
---
 util/src/mio/mio.rs         | 15 +++++++++++++++
 util/src/mio/uds_recv_fd.rs | 11 +++++++++++
 util/src/mio/uds_send_fd.rs |  7 +++++++
 3 files changed, 33 insertions(+)

diff --git a/util/src/mio/mio.rs b/util/src/mio/mio.rs
index b1907e3..ab55566 100644
--- a/util/src/mio/mio.rs
+++ b/util/src/mio/mio.rs
@@ -6,14 +6,23 @@ use crate::{
     result::OkExt,
 };
 
+/// Module containing I/O interest flags for Unix operations
 pub mod interest {
     use mio::Interest;
+
+    /// Interest flag indicating readability
     pub const R: Interest = Interest::READABLE;
+
+    /// Interest flag indicating writability
     pub const W: Interest = Interest::WRITABLE;
+
+    /// Interest flag indicating both readability and writability
     pub const RW: Interest = R.add(W);
 }
 
+/// Extension trait providing additional functionality for Unix listener
 pub trait UnixListenerExt: Sized {
+    /// Creates a new Unix listener by claiming ownership of a raw file descriptor
     fn claim_fd(fd: RawFd) -> anyhow::Result<Self>;
 }
 
@@ -27,9 +36,15 @@ impl UnixListenerExt for UnixListener {
     }
 }
 
+/// Extension trait providing additional functionality for Unix streams
 pub trait UnixStreamExt: Sized {
+    /// Creates a new Unix stream from an owned file descriptor
     fn from_fd(fd: OwnedFd) -> anyhow::Result<Self>;
+
+    /// Claims ownership of a raw file descriptor and creates a new Unix stream
     fn claim_fd(fd: RawFd) -> anyhow::Result<Self>;
+
+    /// Claims ownership of a raw file descriptor in place and creates a new Unix stream
     fn claim_fd_inplace(fd: RawFd) -> anyhow::Result<Self>;
 }
 
diff --git a/util/src/mio/uds_recv_fd.rs b/util/src/mio/uds_recv_fd.rs
index 8e83b83..4511355 100644
--- a/util/src/mio/uds_recv_fd.rs
+++ b/util/src/mio/uds_recv_fd.rs
@@ -9,6 +9,9 @@ use uds::UnixStreamExt as FdPassingExt;
 
 use crate::fd::{claim_fd_inplace, IntoStdioErr};
 
+/// A wrapper around a socket that combines reading from the socket with tracking
+/// received file descriptors. Limits the maximum number of file descriptors that
+/// can be received in a single read operation via the `MAX_FDS` parameter.
 pub struct ReadWithFileDescriptors<const MAX_FDS: usize, Sock, BorrowSock, BorrowFds>
 where
     Sock: FdPassingExt,
@@ -27,6 +30,8 @@ where
     BorrowSock: Borrow<Sock>,
     BorrowFds: BorrowMut<VecDeque<OwnedFd>>,
 {
+    /// Creates a new `ReadWithFileDescriptors` by wrapping a socket and a file
+    /// descriptor queue.
     pub fn new(socket: BorrowSock, fds: BorrowFds) -> Self {
         let _sock_dummy = PhantomData;
         Self {
@@ -36,19 +41,24 @@ where
         }
     }
 
+    /// Consumes the wrapper and returns the underlying socket and file
+    /// descriptor queue.
     pub fn into_parts(self) -> (BorrowSock, BorrowFds) {
         let Self { socket, fds, .. } = self;
         (socket, fds)
     }
 
+    /// Returns a reference to the underlying socket.
     pub fn socket(&self) -> &Sock {
         self.socket.borrow()
     }
 
+    /// Returns a reference to the file descriptor queue.
     pub fn fds(&self) -> &VecDeque<OwnedFd> {
         self.fds.borrow()
     }
 
+    /// Returns a mutable reference to the file descriptor queue.
     pub fn fds_mut(&mut self) -> &mut VecDeque<OwnedFd> {
         self.fds.borrow_mut()
     }
@@ -61,6 +71,7 @@ where
     BorrowSock: BorrowMut<Sock>,
     BorrowFds: BorrowMut<VecDeque<OwnedFd>>,
 {
+    /// Returns a mutable reference to the underlying socket.
     pub fn socket_mut(&mut self) -> &mut Sock {
         self.socket.borrow_mut()
     }
diff --git a/util/src/mio/uds_send_fd.rs b/util/src/mio/uds_send_fd.rs
index 07d5d6f..ac5dad7 100644
--- a/util/src/mio/uds_send_fd.rs
+++ b/util/src/mio/uds_send_fd.rs
@@ -10,6 +10,7 @@ use uds::UnixStreamExt as FdPassingExt;
 
 use crate::{repeat, return_if};
 
+/// A structure that facilitates writing data and file descriptors to a Unix domain socket
 pub struct WriteWithFileDescriptors<Sock, Fd, BorrowSock, BorrowFds>
 where
     Sock: FdPassingExt,
@@ -30,6 +31,7 @@ where
     BorrowSock: Borrow<Sock>,
     BorrowFds: BorrowMut<VecDeque<Fd>>,
 {
+    /// Creates a new `WriteWithFileDescriptors` instance with the given socket and file descriptor queue
     pub fn new(socket: BorrowSock, fds: BorrowFds) -> Self {
         let _sock_dummy = PhantomData;
         let _fd_dummy = PhantomData;
@@ -41,19 +43,23 @@ where
         }
     }
 
+    /// Consumes this instance and returns the underlying socket and file descriptor queue
     pub fn into_parts(self) -> (BorrowSock, BorrowFds) {
         let Self { socket, fds, .. } = self;
         (socket, fds)
     }
 
+    /// Returns a reference to the underlying socket
     pub fn socket(&self) -> &Sock {
         self.socket.borrow()
     }
 
+    /// Returns a reference to the file descriptor queue
     pub fn fds(&self) -> &VecDeque<Fd> {
         self.fds.borrow()
     }
 
+    /// Returns a mutable reference to the file descriptor queue
     pub fn fds_mut(&mut self) -> &mut VecDeque<Fd> {
         self.fds.borrow_mut()
     }
@@ -66,6 +72,7 @@ where
     BorrowSock: BorrowMut<Sock>,
     BorrowFds: BorrowMut<VecDeque<Fd>>,
 {
+    /// Returns a mutable reference to the underlying socket
     pub fn socket_mut(&mut self) -> &mut Sock {
         self.socket.borrow_mut()
     }