From 90ab105504dc658ff8fd1556716953f0c11bddf2 Mon Sep 17 00:00:00 2001
From: Robin Mueller <robin.mueller.m@gmail.com>
Date: Fri, 23 Feb 2024 11:27:13 +0100
Subject: [PATCH] doc improvements and some more renaming

---
 satrs/src/event_man.rs | 58 ++++++++++++++++++++++++------------------
 1 file changed, 33 insertions(+), 25 deletions(-)

diff --git a/satrs/src/event_man.rs b/satrs/src/event_man.rs
index 01086a0..c9880c2 100644
--- a/satrs/src/event_man.rs
+++ b/satrs/src/event_man.rs
@@ -29,8 +29,8 @@
 //!  3. The event manager receives the receiver component as part of a [EventReceiveProvider]
 //!     implementation so all events are routed to the manager.
 //!  4. Create the [send event providers][EventSendProvider]s which allow routing events to
-//!     subscribers. You can now use their [sender IDs][EventSendProvider::id] to subscribe for
-//!     event groups, for example by using the [EventManager::subscribe_single] method.
+//!     subscribers. You can now use their [sender IDs][EventSendProvider::channel_id] to subscribe
+//!     for event groups, for example by using the [EventManager::subscribe_single] method.
 //!  5. Add the send provider as well using the [EventManager::add_sender] call so the event
 //!     manager can route listener groups to a the send provider.
 //!
@@ -91,7 +91,7 @@ pub trait EventReceiveProvider<Event: GenericEvent, AuxDataProvider = Params> {
     /// To allow returning arbitrary additional auxiliary data, a mutable slice is passed to the
     /// [Self::receive] call as well. Receivers can write data to this slice, but care must be taken
     /// to avoid panics due to size missmatches or out of bound writes.
-    fn receive(&self) -> Option<(Event, Option<AuxDataProvider>)>;
+    fn try_recv_event(&self) -> Option<(Event, Option<AuxDataProvider>)>;
 }
 
 pub trait ListenerMapProvider {
@@ -236,6 +236,7 @@ impl<
         }
     }
 
+    /// Add a new sender component which can be used to send events to subscribers.
     pub fn add_sender(&mut self, send_provider: SP) {
         if !self
             .sender_map
@@ -245,6 +246,7 @@ impl<
         }
     }
 
+    /// Generic function to update the event subscribers.
     fn update_listeners(&mut self, key: ListenerKey, sender_id: ChannelId) {
         self.listener_map.add_listener(key, sender_id);
     }
@@ -287,7 +289,7 @@ impl<
                 }
             }
         };
-        if let Some((event, aux_data)) = self.event_receiver.receive() {
+        if let Some((event, aux_data)) = self.event_receiver.try_recv_event() {
             let single_key = ListenerKey::Single(event.raw_as_largest_type());
             send_handler(&single_key, event, &aux_data);
             let group_key = ListenerKey::Group(event.group_id_as_largest_type());
@@ -339,31 +341,14 @@ pub mod alloc_mod {
         }
     }
 
+    /// Default listener map.
+    ///
+    /// Simple implementation which uses a [HashMap] and a [Vec] internally.
     #[derive(Default)]
     pub struct DefaultListenerMap {
         listeners: HashMap<ListenerKey, Vec<ChannelId>>,
     }
 
-    pub struct DefaultSenderMap<
-        SP: EventSendProvider<EV, AUX>,
-        EV: GenericEvent = EventU32,
-        AUX = Params,
-    > {
-        senders: HashMap<ChannelId, SP>,
-        phantom: PhantomData<(EV, AUX)>,
-    }
-
-    impl<SP: EventSendProvider<EV, AUX>, EV: GenericEvent, AUX> Default
-        for DefaultSenderMap<SP, EV, AUX>
-    {
-        fn default() -> Self {
-            Self {
-                senders: Default::default(),
-                phantom: Default::default(),
-            }
-        }
-    }
-
     impl ListenerMapProvider for DefaultListenerMap {
         fn get_listeners(&self) -> Vec<ListenerKey> {
             let mut key_list = Vec::new();
@@ -399,6 +384,29 @@ pub mod alloc_mod {
         }
     }
 
+    /// Default sender map.
+    ///
+    /// Simple implementation which uses a [HashMap] internally.
+    pub struct DefaultSenderMap<
+        SP: EventSendProvider<EV, AUX>,
+        EV: GenericEvent = EventU32,
+        AUX = Params,
+    > {
+        senders: HashMap<ChannelId, SP>,
+        phantom: PhantomData<(EV, AUX)>,
+    }
+
+    impl<SP: EventSendProvider<EV, AUX>, EV: GenericEvent, AUX> Default
+        for DefaultSenderMap<SP, EV, AUX>
+    {
+        fn default() -> Self {
+            Self {
+                senders: Default::default(),
+                phantom: Default::default(),
+            }
+        }
+    }
+
     impl<SP: EventSendProvider<EV, AUX>, EV: GenericEvent, AUX> SenderMapProvider<SP, EV, AUX>
         for DefaultSenderMap<SP, EV, AUX>
     {
@@ -440,7 +448,7 @@ pub mod std_mod {
         }
     }
     impl<Event: GenericEvent + Send> EventReceiveProvider<Event> for MpscEventReceiver<Event> {
-        fn receive(&self) -> Option<EventWithAuxData<Event>> {
+        fn try_recv_event(&self) -> Option<EventWithAuxData<Event>> {
             if let Ok(event_and_data) = self.mpsc_receiver.try_recv() {
                 return Some(event_and_data);
             }