Improve the dependent type theory stuff documentation

Signed-off-by: Alex Saveau <[email protected]>

Author: SUPERCILEX

src/event/epoll.rs

@@ -79,6 +79,7 @@ use crate::fd::{AsFd, OwnedFd};
 use crate::io;
 #[cfg(feature = "alloc")]
 use alloc::vec::Vec;
+pub use buf::EventBuffer;
 use core::ffi::c_void;
 use core::hash::{Hash, Hasher};
 use core::slice;
@@ -192,14 +193,14 @@ pub fn delete(epoll: impl AsFd, source: impl AsFd) -> io::Result<()> {
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/epoll_wait.2.html
 #[inline]
-pub fn wait<B: buf::EventBuffer>(
+pub fn wait<B: EventBuffer>(
     epoll: impl AsFd,
     mut events: B,
     timeout: c::c_int,
 ) -> io::Result<B::Out> {
     unsafe {
-        let nfds = syscalls::epoll_wait(epoll.as_fd(), events.convert(), timeout)?;
-        Ok(events.filled(nfds))
+        let nfds = syscalls::epoll_wait(epoll.as_fd(), events.convert(buf::Internal), timeout)?;
+        Ok(events.filled(nfds, buf::Internal))
     }
 }
 
@@ -442,24 +443,32 @@ mod buf {
     use alloc::vec::Vec;
     use core::mem::MaybeUninit;
 
+    pub struct Internal;
+
+    /// Implementation detail trait to support different return types.
+    ///
+    /// Check the [`Self::Out`] type for each implementation.
     pub trait EventBuffer {
+        /// The return type of this input.
         type Out;
 
-        fn convert(&mut self) -> &mut [MaybeUninit<Event>];
+        #[doc(hidden)]
+        fn convert(&mut self, _: Internal) -> &mut [MaybeUninit<Event>];
 
-        unsafe fn filled(self, count: usize) -> Self::Out;
+        #[doc(hidden)]
+        unsafe fn filled(self, count: usize, _: Internal) -> Self::Out;
     }
 
     #[cfg(feature = "alloc")]
     impl EventBuffer for &mut super::EventVec {
         type Out = ();
 
-        fn convert(&mut self) -> &mut [MaybeUninit<Event>] {
+        fn convert(&mut self, _: Internal) -> &mut [MaybeUninit<Event>] {
             self.events.clear();
             self.events.spare_capacity_mut()
         }
 
-        unsafe fn filled(self, count: usize) -> Self::Out {
+        unsafe fn filled(self, count: usize, _: Internal) -> Self::Out {
             unsafe {
                 self.events.set_len(count);
             }
@@ -470,11 +479,11 @@ mod buf {
     impl EventBuffer for &mut Vec<Event> {
         type Out = ();
 
-        fn convert(&mut self) -> &mut [MaybeUninit<Event>] {
+        fn convert(&mut self, _: Internal) -> &mut [MaybeUninit<Event>] {
             self.spare_capacity_mut()
         }
 
-        unsafe fn filled(self, count: usize) -> Self::Out {
+        unsafe fn filled(self, count: usize, _: Internal) -> Self::Out {
             unsafe {
                 self.set_len(count);
             }
@@ -484,24 +493,24 @@ mod buf {
     impl<'a> EventBuffer for &'a mut [Event] {
         type Out = &'a mut [Event];
 
-        fn convert(&mut self) -> &mut [MaybeUninit<Event>] {
+        fn convert(&mut self, _: Internal) -> &mut [MaybeUninit<Event>] {
             // SAFETY: we (and the kernel) never uninitialize any values
             unsafe { core::mem::transmute::<&mut [Event], &mut [MaybeUninit<Event>]>(self) }
         }
 
-        unsafe fn filled(self, count: usize) -> Self::Out {
+        unsafe fn filled(self, count: usize, _: Internal) -> Self::Out {
             &mut self[..count]
         }
     }
 
     impl<'a> EventBuffer for &'a mut [MaybeUninit<Event>] {
         type Out = &'a mut [Event];
 
-        fn convert(&mut self) -> &mut [MaybeUninit<Event>] {
+        fn convert(&mut self, _: Internal) -> &mut [MaybeUninit<Event>] {
             self
         }
 
-        unsafe fn filled(self, count: usize) -> Self::Out {
+        unsafe fn filled(self, count: usize, _: Internal) -> Self::Out {
             unsafe { split_init(self, count) }.0
         }
     }