Documentation

src/error.rs

@@ -5,15 +5,24 @@ use std::ffi::OsString;
 
 use crate::{FD_NAMES_VAR, FD_NUMBER_VAR, PID_VAR};
 
+#[allow(clippy::module_name_repetitions)]
 #[derive(Debug)]
 pub enum ReceiveError {
+    /// The environement variable `LISTEN_PID` didn't exists (probably meaning that no file descriptor was passed to us).
     NoListenPID,
+    /// The environement variable `LISTEN_PID` (which should be a decimal number) isn't unicode.
     NotUnicodeListenPID(OsString),
+    /// The environement variable `LISTEN_PID` couldn't be parsed as a [`u32`] (real [`pid_t`](libc::pid_t) due to [`std::process::id`])
     ListenPIDParse(ParseIntError),
+    /// The environement variable `LISTEN_FDS` didn't exists (probably meaning that no file descriptor was passed to us)
     NoListenFD,
+    /// The environement variable `LISTEN_FDS` (which should be a decimal number) isn't unicode.
     NotUnicodeListenFD(OsString),
+    /// The environement variable `LISTEN_FDS` couldn't be parsed as a [`usize`].
     ListenFDParse(ParseIntError),
+    /// Our PID isn't the one expected as per `LISTEN_PID`.
     PidMismatch { expected: u32, found: u32 },
+    /// We couldn't get the file descriptors (see [`GetFdsError`])
     GetFds(GetFdsError),
 }
 
@@ -36,24 +45,26 @@ impl Display for ReceiveError {
 impl Error for ReceiveError {
     fn source(&self) -> Option<&(dyn Error + 'static)> {
         match self {
-            ReceiveError::NoListenPID => None,
-            ReceiveError::NotUnicodeListenPID(_) => None,
-            ReceiveError::ListenPIDParse(error) => Some(error),
-            ReceiveError::NoListenFD => None,
-            ReceiveError::NotUnicodeListenFD(_) => None,
-            ReceiveError::ListenFDParse(error) => Some(error),
-            ReceiveError::PidMismatch {
+            ReceiveError::NoListenPID
+            | ReceiveError::NotUnicodeListenPID(_)
+            | ReceiveError::NoListenFD
+            | ReceiveError::NotUnicodeListenFD(_)
+            | ReceiveError::PidMismatch {
                 expected: _,
                 found: _,
             } => None,
+            ReceiveError::ListenPIDParse(error) | ReceiveError::ListenFDParse(error) => Some(error),
             ReceiveError::GetFds(error) => Some(error),
         }
     }
 }
 
+#[allow(clippy::module_name_repetitions)]
 #[derive(Debug)]
 pub enum ReceiveNameError {
+    /// The variable `LISTEN_FDNAMES` didn't exists.
     NoListenFDName,
+    /// No file descriptors could be received.
     Receive(ReceiveError),
 }
 
@@ -84,6 +95,7 @@ impl Error for ReceiveNameError {
     }
 }
 
+#[allow(clippy::module_name_repetitions)]
 #[derive(Debug)]
 pub enum GetFdsError {
     TooManyFDs(usize),

src/lib.rs

@@ -79,6 +79,10 @@ impl FileDescriptor {
     ///
     /// This isn't necessarily limited to File descriptor of listening sockets, IPCs or FIFOs but also anything that is in the file descriptor store.
     /// The file descriptores are duplicated using [`fcntl_dupfd_cloexec`](rustix::fs::fcntl_dupfd_cloexec) so they can safely be used from rust and will not be propagated to children process automatically.
+    ///
+    /// # Errors
+    ///
+    /// This function will fail if no file descriptor colud be received which might not actually be an error. See [`ReceiveError`] for details.
     pub fn receive(unset_env: bool) -> Result<impl IntoIterator<Item = Self>, ReceiveError> {
         let pid = env::var_os(PID_VAR).ok_or(ReceiveError::NoListenPID)?;
         let fds = env::var_os(FD_NUMBER_VAR).ok_or(ReceiveError::NoListenFD)?;
@@ -119,6 +123,10 @@ impl FileDescriptor {
     ///
     /// This isn't necessarily limited to File descriptor of listening sockets, IPCs or FIFOs but also anything that is in the file descriptor store.
     /// The file descriptores are duplicated using [`fcntl_dupfd_cloexec`](rustix::fs::fcntl_dupfd_cloexec) so they can safely be used from rust and will not be propagated to children process automatically.
+    ///
+    /// # Errors
+    ///
+    /// This function will fail if no file descriptors could be obtained or the names associated with them couldn't be obtained. See [`ReceiveNameError`] for details.
     pub fn receive_with_names(
         unset_env: bool,
     ) -> Result<impl IntoIterator<Item = (Self, OsString)>, ReceiveNameError> {