Add some unit tests and documentation to the crate. No functional changes.

src/rust/lqos_utils/src/fdtimer.rs

@@ -5,6 +5,13 @@ use nix::sys::{
 };
 use std::sync::atomic::AtomicBool;
 
+/// `periodic` runs a function at a given interval.
+/// 
+/// ## Parameters
+/// 
+/// * `interval_ms`: the interval in milliseconds.
+/// * `task_name`: the name of the task to run.
+/// * `tick_function`: the function to run at the given interval.
 pub fn periodic(
   interval_ms: u64,
   task_name: &str,

src/rust/lqos_utils/src/file_watcher.rs

@@ -145,10 +145,14 @@ impl FileWatcher {
   }
 }
 
+/// Errors that can occur when watching a file.
 #[derive(Error, Debug)]
 pub enum WatchedFileError {
+  /// Unable to create the file watcher.
   #[error("Unable to create watcher")]
   CreateWatcherError,
+
+  /// Unable to start the file watcher system.
   #[error("Unable to start watcher")]
   StartWatcherError,
 }

src/rust/lqos_utils/src/hex_string.rs

@@ -37,6 +37,7 @@ pub fn read_hex_string(s: &str) -> Result<u32, HexParseError> {
 /// parsing a string into a `u32` hex number.
 #[derive(Error, Debug)]
 pub enum HexParseError {
+  /// The hex string could not be decoded
   #[error("Unable to decode string into valid hex")]
   ParseError,
 }

src/rust/lqos_utils/src/lib.rs

@@ -1,10 +1,24 @@
+//! Collection of utility functions for LibreQoS
+
+#![warn(missing_docs)]
 mod commands;
+
+/// Provides a Linux file-descriptor based timing service.
 pub mod fdtimer;
+
+/// Wrapper for watching when a file has changed.
 pub mod file_watcher;
+
+/// Utilities for handling strings in hex format
 pub mod hex_string;
+
+/// Utilities for scaling bits and packets to human-readable format
 pub mod packet_scale;
 mod string_table_enum;
+
+/// Utilities dealing with Unix Timestamps
 pub mod unix_time;
 mod xdp_ip_address;
 
-pub use xdp_ip_address::XdpIpAddress;
+/// XDP compatible IP Address
+pub use xdp_ip_address::XdpIpAddress;

src/rust/lqos_utils/src/packet_scale.rs

@@ -1,23 +1,49 @@
+/// Scale a number of packets to a human readable string.
+/// 
+/// ## Parameters
+/// * `n`: the number of packets to scale
 pub fn scale_packets(n: u64) -> String {
-  if n > 1_000_000_000 {
+  if n >= 1_000_000_000 {
     format!("{:.2} gpps", n as f32 / 1_000_000_000.0)
-  } else if n > 1_000_000 {
+  } else if n >= 1_000_000 {
     format!("{:.2} mpps", n as f32 / 1_000_000.0)
-  } else if n > 1_000 {
+  } else if n >= 1_000 {
     format!("{:.2} kpps", n as f32 / 1_000.0)
   } else {
-    format!("{n}  pps")
+    format!("{n} pps")
   }
 }
 
+/// Scale a number of bits to a human readable string.
+/// 
+/// ## Parameters
+/// * `n`: the number of bits to scale
 pub fn scale_bits(n: u64) -> String {
-  if n > 1_000_000_000 {
+  if n >= 1_000_000_000 {
     format!("{:.2} gbit/s", n as f32 / 1_000_000_000.0)
-  } else if n > 1_000_000 {
+  } else if n >= 1_000_000 {
     format!("{:.2} mbit/s", n as f32 / 1_000_000.0)
-  } else if n > 1_000 {
+  } else if n >= 1_000 {
     format!("{:.2} kbit/s", n as f32 / 1_000.0)
   } else {
-    format!("{n}  bit/s")
+    format!("{n} bit/s")
   }
 }
+
+#[cfg(test)]
+mod test {
+  #[test]
+  fn test_scale_packets() {
+    assert_eq!(super::scale_packets(1), "1 pps");
+    assert_eq!(super::scale_packets(1000), "1.00 kpps");
+    assert_eq!(super::scale_packets(1000000), "1.00 mpps");
+    assert_eq!(super::scale_packets(1000000000), "1.00 gpps");
+  }
+
+  #[test]
+  fn test_scale_bits() {
+    assert_eq!(super::scale_bits(1), "1 bit/s");
+    assert_eq!(super::scale_bits(1000), "1.00 kbit/s");
+    assert_eq!(super::scale_bits(1000000), "1.00 mbit/s");
+    assert_eq!(super::scale_bits(1000000000), "1.00 gbit/s");}
+}

src/rust/lqos_utils/src/string_table_enum.rs

@@ -1,3 +1,9 @@
+/// Helper macro to create an enum that can be serialized to a string
+/// and deserialized from a string.
+/// 
+/// ## Parameters
+/// * `$enum_name`: the name of the enum to create
+/// * `$($option:ident),*`: the options of the enum
 #[macro_export]
 macro_rules! string_table_enum {
     ($enum_name: ident, $($option:ident),*) => {
@@ -36,6 +42,13 @@ macro_rules! string_table_enum {
     };
 }
 
+/// Helper macro to create an enum that can be serialized to a string
+/// and deserialized from a string. Adds explicit support for dashes
+/// in identifiers.
+/// 
+/// ## Parameters
+/// * `$enum_name`: the name of the enum to create
+/// * `$($option:ident),*`: the options of the enum
 #[macro_export]
 macro_rules! dashy_table_enum {
     ($enum_name: ident, $($option:ident),*) => {

src/rust/lqos_utils/src/unix_time.rs

@@ -32,8 +32,10 @@ pub fn time_since_boot() -> Result<TimeSpec, TimeError> {
   }
 }
 
+/// Error type for time functions.
 #[derive(Error, Debug)]
 pub enum TimeError {
+  /// The clock isn't ready yet.
   #[error("Clock not ready")]
   ClockNotReady,
 }