From 6dae26212dc16e8458b536995511a950d6cfcc0d Mon Sep 17 00:00:00 2001
From: Mathieu Trossevin <mathieu.trossevin@gmail.com>
Date: Fri, 5 Jan 2024 22:49:21 +0100
Subject: [PATCH] notify: Even better documentation

---
 src/notify/types.rs | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/notify/types.rs b/src/notify/types.rs
index f8fb474..a4d6a3c 100644
--- a/src/notify/types.rs
+++ b/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> {
-        if value.is_negative() {
+    fn try_from(milliseconds: core::num::NonZeroI32) -> Result<Self, Self::Error> {
+        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);