From 692dff96a9834e64be6e76970665fcc0713cebdf Mon Sep 17 00:00:00 2001
From: Marvin Drescher <mdr@ssv-embedded.de>
Date: Thu, 20 Jun 2024 14:27:44 +0200
Subject: [PATCH] docs: document filter

---
 rumqttd/src/lib.rs           |  3 +-
 rumqttd/src/router/filter.rs | 56 +++++++++++++++++++++++++++++-------
 2 files changed, 47 insertions(+), 12 deletions(-)

diff --git a/rumqttd/src/lib.rs b/rumqttd/src/lib.rs
index 9f5742f3..73fa574c 100644
--- a/rumqttd/src/lib.rs
+++ b/rumqttd/src/lib.rs
@@ -6,7 +6,6 @@ use std::pin::Pin;
 use std::sync::Arc;
 use std::{collections::HashMap, path::Path};
 
-use router::PublishFilterRef;
 use serde::{Deserialize, Serialize};
 use tracing_subscriber::{
     filter::EnvFilter,
@@ -22,7 +21,7 @@ use tracing_subscriber::{
 pub use link::alerts;
 pub use link::local;
 pub use link::meters;
-pub use router::{Alert, IncomingMeter, Meter, Notification, OutgoingMeter};
+pub use router::{Alert, IncomingMeter, Meter, Notification, OutgoingMeter, PublishFilter, PublishFilterRef};
 use segments::Storage;
 pub use server::Broker;
 
diff --git a/rumqttd/src/router/filter.rs b/rumqttd/src/router/filter.rs
index 42b5d768..ebd3e2a7 100644
--- a/rumqttd/src/router/filter.rs
+++ b/rumqttd/src/router/filter.rs
@@ -2,10 +2,17 @@ use std::{fmt::Debug, ops::Deref, sync::Arc};
 
 use crate::protocol::{Publish, PublishProperties};
 
+/// Filter for [`Publish`] packets
 pub trait PublishFilter {
+    /// Determines weather an [`Publish`] packet should be processed
+    /// Arguments:
+    /// * `packet`: to be published, may be modified if necessary
+    /// * `properties`: received along with the packet, may be `None` for older MQTT versions
+    /// Returns: [`bool`] indicating if the packet should be processed
     fn filter(&self, packet: &mut Publish, properties: Option<&mut PublishProperties>) -> bool;
 }
 
+/// Container for either an owned [`PublishFilter`] or an `'static` reference
 #[derive(Clone)]
 pub enum PublishFilterRef {
     Owned(Arc<dyn PublishFilter + Send + Sync>),
@@ -15,8 +22,8 @@ pub enum PublishFilterRef {
 impl Debug for PublishFilterRef {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
-            Self::Owned(arg0) => f.debug_tuple("Owned").finish(),
-            Self::Static(arg0) => f.debug_tuple("Static").finish(),
+            Self::Owned(_arg0) => f.debug_tuple("Owned").finish(),
+            Self::Static(_arg0) => f.debug_tuple("Static").finish(),
         }
     }
 }
@@ -32,6 +39,7 @@ impl Deref for PublishFilterRef {
     }
 }
 
+/// Implements [`PublishFilter`] for any ordinary function 
 impl<F> PublishFilter for F
 where
     F: Fn(&mut Publish, Option<&mut PublishProperties>) -> bool + Send + Sync,
@@ -41,6 +49,16 @@ where
     }
 }
 
+/// Implements the conversion 
+/// ```rust
+/// # use rumqttd::{protocol::{Publish, PublishProperties}, PublishFilterRef};
+/// fn filter_static(packet: &mut Publish, properties: Option<&mut PublishProperties>) -> bool {
+///     todo!()
+/// }
+///
+/// let filter = PublishFilterRef::from(&filter_static);
+/// # assert!(matches!(filter, PublishFilterRef::Static(_)));
+/// ```
 impl<F> From<&'static F> for PublishFilterRef
 where
     F: Fn(&mut Publish, Option<&mut PublishProperties>) -> bool + Send + Sync,
@@ -50,20 +68,38 @@ where
     }
 }
 
-impl<T> From<Box<T>> for PublishFilterRef
+/// Implements the conversion 
+/// ```rust
+/// # use std::boxed::Box;
+/// # use rumqttd::{protocol::{Publish, PublishProperties}, PublishFilter, PublishFilterRef};
+/// #[derive(Clone)]
+/// struct MyFilter {}
+///
+/// impl PublishFilter for MyFilter {
+///     fn filter(&self, packet: &mut Publish, properties: Option<&mut PublishProperties>) -> bool {
+///         todo!()
+///     }
+/// }
+/// let boxed: Box<MyFilter> = Box::new(MyFilter {});
+///
+/// let filter = PublishFilterRef::from(boxed);
+/// # assert!(matches!(filter, PublishFilterRef::Owned(_)));
+/// ```
+impl<T> From<Arc<T>> for PublishFilterRef
 where
     T: PublishFilter + 'static + Send + Sync,
 {
-    fn from(value: Box<T>) -> Self {
-        Self::Owned(Arc::<T>::from(value))
+    fn from(value: Arc<T>) -> Self {
+        Self::Owned(value)
     }
 }
-impl<T> From<Arc<T>> for PublishFilterRef
+
+impl<T> From<Box<T>> for PublishFilterRef
 where
     T: PublishFilter + 'static + Send + Sync,
 {
-    fn from(value: Arc<T>) -> Self {
-        Self::Owned(value)
+    fn from(value: Box<T>) -> Self {
+        Self::Owned(Arc::<T>::from(value))
     }
 }
 
@@ -71,13 +107,13 @@ where
 mod tests {
     use super::*;
 
-    fn filter_static(packet: &mut Publish, properties: Option<&mut PublishProperties>) -> bool {
+    fn filter_static(_packet: &mut Publish, _properties: Option<&mut PublishProperties>) -> bool {
         true
     }
     struct Prejudiced(bool);
 
     impl PublishFilter for Prejudiced {
-        fn filter(&self, packet: &mut Publish, properties: Option<&mut PublishProperties>) -> bool {
+        fn filter(&self, _packet: &mut Publish,_propertiess: Option<&mut PublishProperties>) -> bool {
             self.0
         }
     }