doc sweep!

wakey-linux/src/dhcp.rs

@@ -5,6 +5,7 @@ use wakey_core::{DhcpLease, DhcpLeaseWithState};
 
 const MAC_NAME_CACHE: &str = "/tmp/wakey_mac_names.json";
 
+/// Load the MAC-to-name cache used to preserve useful names across lease churn.
 pub async fn load_mac_name_cache() -> io::Result<std::collections::BTreeMap<String, String>> {
     match tokio::fs::read_to_string(MAC_NAME_CACHE).await {
         Ok(s) => serde_json::from_str(&s).map_err(io::Error::other),
@@ -13,12 +14,14 @@ pub async fn load_mac_name_cache() -> io::Result<std::collections::BTreeMap<Stri
     }
 }
 
+/// Persist the MAC-to-name cache back to disk.
 async fn save_mac_name_cache(map: &std::collections::BTreeMap<String, String>) -> io::Result<()> {
     let s = serde_json::to_string(map).map_err(io::Error::other)?;
     let _ = tokio::fs::write(MAC_NAME_CACHE, s).await;
     Ok(())
 }
 
+/// Parse one `dnsmasq`-style DHCP lease line.
 pub fn parse_dhcp_lease_line(line: &str) -> Option<DhcpLease> {
     let mut c = line.split_whitespace();
     let expires_epoch: u64 = c.next()?.parse().ok()?;
@@ -33,6 +36,7 @@ pub fn parse_dhcp_lease_line(line: &str) -> Option<DhcpLease> {
     })
 }
 
+/// Read raw DHCP leases from `/tmp/dhcp.leases`.
 pub async fn read_dhcp_leases() -> io::Result<Vec<DhcpLease>> {
     match tokio::fs::read_to_string("/tmp/dhcp.leases").await {
         Ok(file) => Ok(file.lines().filter_map(parse_dhcp_lease_line).collect()),
@@ -41,6 +45,7 @@ pub async fn read_dhcp_leases() -> io::Result<Vec<DhcpLease>> {
     }
 }
 
+/// Read DHCP leases and fill missing names from the MAC-name cache.
 pub async fn read_dhcp_leases_with_names() -> io::Result<Vec<DhcpLease>> {
     let leases = read_dhcp_leases().await?;
     let mut cache = load_mac_name_cache().await.unwrap_or_default();
@@ -64,6 +69,7 @@ pub async fn read_dhcp_leases_with_names() -> io::Result<Vec<DhcpLease>> {
     Ok(leases_with_names)
 }
 
+/// Enrich DHCP leases with the best currently known neighbor state per IP.
 pub async fn enrich_leases_with_nud_state(leases: Vec<DhcpLease>) -> Vec<DhcpLeaseWithState> {
     let ips: Vec<IpAddr> = leases.iter().map(|l| l.ip).collect();
     let mut map: std::collections::HashMap<IpAddr, wakey_core::NeighborState> =