doc sweep!

wakey-linux/src/devices/interfaces.rs

@@ -3,6 +3,10 @@ use lda_ipjs::subcommands::address;
 use std::collections::HashSet;
 use wakey_core::{InterfaceAddr, InterfaceSummary};
 
+/// Discover interface names from Linux without requiring `ip`.
+///
+/// This is the lowest-common-denominator interface listing path and is used for
+/// quick existence checks and legacy string-only callers.
 pub async fn list_devs() -> HashSet<String> {
     fn get_dev() -> HashSet<String> {
         let mut devs: HashSet<String> = HashSet::new();
@@ -50,6 +54,15 @@ pub async fn devs_sorted() -> Vec<String> {
     v
 }
 
+/// Build condensed interface summaries from Linux address data.
+///
+/// On Unix this prefers the `ipjs` netlink-backed address path; elsewhere it
+/// falls back to the JSON command path. The result is not a full `ip address show`
+/// dump. It is a smaller projection containing the parts `wakey` currently uses:
+/// interface name/index, operstate, MAC, bound addresses, and IPv4 broadcast
+/// addresses for Wake-on-LAN delivery.
+///
+/// Loopback is intentionally excluded.
 pub async fn list_interface_summaries() -> Result<Vec<InterfaceSummary>> {
     #[cfg(unix)]
     let rows = address::nl::get(None)
@@ -91,6 +104,7 @@ pub async fn list_interface_summaries() -> Result<Vec<InterfaceSummary>> {
     Ok(out)
 }
 
+/// Return whether a named interface exists according to [`list_devs`].
 pub async fn has_dev(name: &str) -> bool {
     list_devs().await.contains(name)
 }

wakey-linux/src/devices/neighbors.rs

@@ -5,6 +5,7 @@ use std::collections::HashSet;
 use std::net::IpAddr;
 use wakey_core::{DeviceQuery, NeighborEntry, NeighborState};
 
+/// Resolve a hostname through the local resolver and return all reported IPs.
 pub async fn get_ips(machine_name: &str) -> Result<impl Iterator<Item = IpAddr>> {
     Ok(tokio::net::lookup_host((machine_name, 0))
         .await
@@ -12,6 +13,11 @@ pub async fn get_ips(machine_name: &str) -> Result<impl Iterator<Item = IpAddr>>
         .map(|c| c.ip()))
 }
 
+/// Query Linux neighbor data and project it into `wakey-core` neighbor rows.
+///
+/// `machine_names` are resolved first and intersected with any explicit `ips`
+/// filter. On Unix this prefers the netlink-backed `ipjs` path; elsewhere it
+/// falls back to the JSON command backend.
 pub async fn get_neighbors(
     machine_names: &[impl AsRef<str>],
     ips: &[IpAddr],
@@ -100,6 +106,7 @@ pub async fn get_neighbors(
     }
 }
 
+/// Convenience wrapper around [`get_neighbors`] using the legacy `DeviceQuery`.
 pub async fn query_status(query: &DeviceQuery) -> Result<Vec<NeighborEntry>> {
     get_neighbors(
         query.name.as_slice(),

wakey-linux/src/devices/query.rs

@@ -4,6 +4,10 @@ use wakey_core::{NeighborState, QueryInput, parse};
 
 use crate::devices::interfaces::has_dev;
 
+/// Classify one free-form input string into the most specific query variant.
+///
+/// The current precedence is:
+/// IP address, MAC address, neighbor state, interface name, then plain text.
 pub async fn classify_query(q: String) -> QueryInput {
     let s = parse::extract_host(&q);
     if let Some(ip) = parse::parse_numeric_ipv4(s).or_else(|| s.parse::<IpAddr>().ok()) {