doc sweep!

wakey-core/src/model/device.rs

@@ -6,6 +6,7 @@ use std::net::IpAddr;
 use crate::model::{DhcpLease, NeighborEntry, NeighborState};
 use crate::parse::mac;
 
+/// Product-level presence derived from raw neighbor state.
 #[derive(Debug, PartialEq, Eq, Clone, Copy, Hash, Serialize, serde::Deserialize, Default)]
 #[serde(rename_all = "snake_case")]
 pub enum Presence {
@@ -31,12 +32,17 @@ impl From<NeighborState> for Presence {
     }
 }
 
+/// MAC-first identifier for a device aggregate.
 #[derive(Debug, PartialEq, Eq, Clone, Hash, Serialize)]
 pub struct DeviceId {
     #[serde(with = "mac")]
     pub mac: MacAddr,
 }
 
+/// Merged view of one discovered network identity.
+///
+/// This aggregates facts from DHCP leases and neighbor-table rows into a more
+/// useful application-level shape.
 #[skip_serializing_none]
 #[derive(Debug, Clone, Serialize)]
 pub struct Device {
@@ -52,6 +58,7 @@ pub struct Device {
 }
 
 impl Device {
+    /// Merge raw neighbor and DHCP facts into one device aggregate.
     pub fn from_parts(neighbors: Vec<NeighborEntry>, leases: Vec<DhcpLease>) -> Self {
         use std::collections::BTreeSet;
 
@@ -117,6 +124,7 @@ impl From<u8> for Presence {
     }
 }
 
+/// Collection of merged discovered devices.
 #[derive(Debug, Default, Clone, Serialize)]
 pub struct DeviceInventory {
     pub devices: Vec<Device>,

wakey-core/src/model/dhcp.rs

@@ -6,6 +6,7 @@ use std::net::IpAddr;
 use crate::model::NeighborState;
 use crate::parse::mac;
 
+/// One parsed DHCP lease row.
 #[derive(Debug, Clone, Serialize)]
 pub struct DhcpLease {
     pub expires_epoch: u64,
@@ -15,6 +16,7 @@ pub struct DhcpLease {
     pub name: Option<String>,
 }
 
+/// DHCP lease row plus optional current neighbor-state enrichment.
 #[skip_serializing_none]
 #[derive(Debug, Clone, Serialize)]
 pub struct DhcpLeaseWithState {
@@ -23,6 +25,7 @@ pub struct DhcpLeaseWithState {
     pub nud_state: Option<NeighborState>,
 }
 
+/// Options for lease retrieval from the service layer.
 #[derive(Debug, Default, Clone, Serialize, Deserialize)]
 pub struct LeaseQuery {
     pub include_state: bool,

wakey-core/src/model/interface.rs

@@ -4,23 +4,40 @@ use serde_with::skip_serializing_none;
 
 use crate::parse::mac;
 
+/// A condensed, operator-oriented view of one network interface.
+///
+/// This is intentionally smaller than the full Linux `ip address show` / `ip link show`
+/// payload. It keeps the fields that are currently useful to `wakey`:
+/// interface identity, operational state, MAC address, bound addresses, and
+/// IPv4 broadcast targets.
 #[skip_serializing_none]
 #[derive(Debug, Clone, Serialize)]
 pub struct InterfaceSummary {
+    /// Kernel interface index.
     pub ifindex: u32,
+    /// Interface name such as `br-lan`, `eth0`, or `wlan0`.
     pub ifname: String,
+    /// Lowercased operational state such as `up`, `down`, or `unknown`.
     pub operstate: String,
     #[serde(with = "mac::option_mac")]
+    /// Link-layer address when one exists.
     pub mac: Option<MacAddr>,
+    /// Interface-bound addresses projected into a smaller usable shape.
     pub addrs: Vec<InterfaceAddr>,
 }
 
+/// A condensed view of one bound interface address.
 #[skip_serializing_none]
 #[derive(Debug, Clone, Serialize)]
 pub struct InterfaceAddr {
+    /// Address family such as `inet` or `inet6`.
     pub family: Option<String>,
+    /// CIDR notation such as `192.168.1.1/24`.
     pub cidr: Option<String>,
+    /// IPv4 broadcast target when Linux reports one.
     pub broadcast: Option<std::net::Ipv4Addr>,
+    /// Linux-reported address scope, for example `global` or `link`.
     pub scope: Option<String>,
+    /// Optional Linux label for the address entry.
     pub label: Option<String>,
 }

wakey-core/src/model/neighbor.rs

@@ -6,6 +6,7 @@ use strum::{Display, EnumString};
 
 use crate::parse::mac;
 
+/// One neighbor-table row, typically derived from `ip neigh` or netlink.
 #[skip_serializing_none]
 #[derive(Debug, PartialEq, Eq, Clone, Hash, Serialize)]
 pub struct NeighborEntry {
@@ -16,6 +17,7 @@ pub struct NeighborEntry {
     pub state: NeighborState,
 }
 
+/// Linux neighbor reachability state.
 #[derive(
     Debug, PartialEq, Eq, EnumString, Display, Clone, Copy, Hash, Serialize, Deserialize, Default,
 )]
@@ -36,6 +38,7 @@ pub enum NeighborState {
 }
 
 impl NeighborState {
+    /// Lowercase CLI argument form used by `ip neigh`.
     pub const fn as_ip_neigh_arg(self) -> &'static str {
         match self {
             NeighborState::Permanent => "permanent",
@@ -50,6 +53,7 @@ impl NeighborState {
         }
     }
 
+    /// Ordering rank used when choosing the “best” state among multiple rows.
     pub const fn rank(self) -> u8 {
         match self {
             NeighborState::Permanent | NeighborState::Reachable => 5,
@@ -74,6 +78,7 @@ impl Ord for NeighborState {
     }
 }
 
+/// Errors returned when parsing a text `ip neigh` line.
 #[derive(Debug, Display, thiserror::Error)]
 pub enum NeighborParseError {
     IpWhere,
@@ -83,6 +88,7 @@ pub enum NeighborParseError {
     StateParseError(#[from] strum::ParseError),
 }
 
+/// Parse one textual `ip neigh` line into a typed neighbor row.
 pub fn parse_neighbor_line(s: &str) -> Result<NeighborEntry, NeighborParseError> {
     let mut it = s.split_whitespace();
     let ip: IpAddr = it.next().ok_or(NeighborParseError::IpWhere)?.parse()?;

wakey-core/src/model/query.rs

@@ -5,6 +5,10 @@ use std::net::IpAddr;
 
 use crate::model::NeighborState;
 
+/// Legacy-compatible query shape used by HTTP and service adapters.
+///
+/// `name` carries free-form text selection, while `filter` carries explicit
+/// machine-readable filters such as IPs, MACs, interfaces, and neighbor states.
 #[derive(Debug, Default, Clone, Hash, Deserialize, Serialize)]
 pub struct DeviceQuery {
     pub name: Option<String>,
@@ -12,6 +16,7 @@ pub struct DeviceQuery {
     pub filter: DeviceFilters,
 }
 
+/// Explicit device filters for source- and service-level queries.
 #[serde_as]
 #[derive(Debug, Default, Clone, Hash, Serialize, Deserialize)]
 pub struct DeviceFilters {
@@ -29,11 +34,13 @@ pub struct DeviceFilters {
     pub macs: Vec<MacAddr>,
 }
 
+/// Path helper for routes that receive a single `{name}` segment.
 #[derive(Debug, Default, Clone, Hash, Deserialize)]
 pub struct NamePath {
     pub name: String,
 }
 
+/// Low-level classified input used by Linux query classification.
 #[derive(Debug)]
 pub enum QueryInput {
     Ip(IpAddr),
@@ -43,6 +50,7 @@ pub enum QueryInput {
     Name(String),
 }
 
+/// Higher-level typed selector used by the service layer.
 #[derive(Debug, Clone)]
 pub enum Query {
     Text(String),

wakey-core/src/model/wake.rs

@@ -5,6 +5,9 @@ use std::net::IpAddr;
 
 use crate::parse::mac;
 
+/// Concrete Wake-on-LAN destination fields.
+///
+/// A fully usable target needs both an IP address and a MAC address.
 #[skip_serializing_none]
 #[derive(Debug, Serialize, Deserialize, Clone, Copy, Hash, PartialEq, Eq)]
 pub struct WakeTarget {
@@ -15,6 +18,7 @@ pub struct WakeTarget {
 }
 
 impl WakeTarget {
+    /// Return whether this target has both fields needed to send WoL.
     pub const fn is_complete(&self) -> bool {
         matches!(
             self,
@@ -26,11 +30,13 @@ impl WakeTarget {
     }
 }
 
+/// Result of waking one or more targets.
 #[derive(Debug, Serialize, Clone)]
 pub struct WakeResult {
     pub result: Vec<WakeTargetResult>,
 }
 
+/// Per-target wake result row.
 #[skip_serializing_none]
 #[derive(Debug, Serialize, Clone, Copy)]
 pub struct WakeTargetResult {
@@ -39,6 +45,7 @@ pub struct WakeTargetResult {
     pub status: WakeStatus,
 }
 
+/// Outcome of trying to wake one target.
 #[derive(Debug, Serialize, Clone, Copy, Hash, PartialEq, Eq)]
 #[serde(rename_all = "snake_case")]
 pub enum WakeStatus {
@@ -49,6 +56,7 @@ pub enum WakeStatus {
 }
 
 impl WakeTargetResult {
+    /// Construct an incomplete result for a target missing required fields.
     pub const fn incomplete(target: WakeTarget) -> Self {
         Self {
             target,