notify: Even better documentation

src/notify/types.rs

@@ -109,10 +109,14 @@ impl Display for Microseconds {
     }
 }
 
+/// Timeout for the [`Notifier::barrier()`](super::Notifier::barrier).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum BarrierTimeout {
+    /// Will block indefinitely.
     Infinite,
+    /// Will not block at all and return immediately even if no event has happened.
     Immediate,
+    /// Will block for a number of milliseconds.
     NonZero(PollTimeout),
 }
 
@@ -126,17 +130,18 @@ impl BarrierTimeout {
     }
 }
 
+/// Variant of [`BarrierTimeout`] for positive timeout.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct PollTimeout(core::num::NonZeroI32);
 
 impl TryFrom<core::num::NonZeroI32> for PollTimeout {
     type Error = error::PollTimeoutFromIntError;
 
-    fn try_from(value: core::num::NonZeroI32) -> Result<Self, Self::Error> {
+    fn try_from(milliseconds: core::num::NonZeroI32) -> Result<Self, Self::Error> {
-        if value.is_negative() {
+        if milliseconds.is_negative() {
             return Err(Self::Error::Negative);
         }
-        Ok(Self(value))
+        Ok(Self(milliseconds))
     }
 }
 
@@ -173,6 +178,9 @@ impl Display for BusError<'_> {
     }
 }
 
+/// An arbitrary custom state other than `BARRIER=1`.
+///
+/// `BARRIER=1` is blocked as it result in special expectations by the protocol.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct OtherState<'a>(&'a str);