doc sweep!

ipjs/src/subcommands/address/mod.rs

@@ -1,8 +1,7 @@
-//! ts
+//! Typed wrappers for `ip -j address show`.
 //!
-//! deals with both ip a (addroutput) and ip l (commonoutput)
-//!
-//! lowk why its free but its indirection and its ass
+//! This module is intentionally close to the Linux output shape while still
+//! tightening a few fields into more useful Rust types.
 
 pub mod json;
 #[cfg(all(unix, feature = "experimental-nl"))]
@@ -16,22 +15,21 @@ use std::net::{IpAddr, Ipv4Addr};
 
 use crate::subcommands::link::OperState;
 
-/// i dont include what i dont know about (almost all ts)
+/// One interface row from `ip -j address show`.
 #[derive(Serialize, Debug, Deserialize)]
 pub struct AddrOutput {
     pub ifindex: u32,
     pub ifname: String,
-    /// i imagine UP or DOWN, unknown
+    /// Interface operational state.
     pub operstate: OperState,
-    // 6 has a serde and the enum doesnt? why. (serializing ts is ass although... im not given an array. they string formatted ts)
     #[serde(with = "option_mac", default)]
     pub address: Option<MacAddr>,
-    #[serde(default)] // i wish we have intellisense for this... fuck you metaprogramming
+    /// Per-address entries attached to this interface.
+    #[serde(default)]
     pub addr_info: Vec<AddrInfo>,
 }
 
-// i be copying
-// Raw JSON shape from ip -j -4 address show
+/// One address entry nested under an interface row.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct AddrInfo {
     pub family: Option<AddressFamily>,
@@ -43,9 +41,9 @@ pub struct AddrInfo {
 
     pub scope: Option<String>,
     pub label: Option<String>,
-    // many more exist; we only take what we need
 }
 
+/// Address family used by `ip address` output.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AddressFamily {
     Inet,
@@ -90,6 +88,10 @@ impl<'de> Deserialize<'de> for AddressFamily {
     }
 }
 
+/// Raw parsed local address plus prefix length.
+///
+/// This is still a source-shaped type; callers that need a guaranteed usable
+/// CIDR should validate that both fields are present.
 #[derive(Debug, Default, Clone, Deserialize, Serialize)]
 pub struct InterfaceCidr {
     pub local: Option<IpAddr>,
@@ -103,37 +105,45 @@ impl InterfaceCidr {
 }
 
 impl AddrInfo {
+    /// Return the parsed local IP address when present.
     pub fn local_addr(&self) -> Option<IpAddr> {
         self.cidr.local
     }
 
+    /// Return the parsed prefix length when present.
     pub fn prefixlen(&self) -> Option<u8> {
         self.cidr.prefixlen
     }
 
+    /// Return whether this row is IPv4.
     pub fn is_ipv4(&self) -> bool {
         matches!(self.family, Some(AddressFamily::Inet))
     }
 
+    /// Return whether this row is IPv6.
     pub fn is_ipv6(&self) -> bool {
         matches!(self.family, Some(AddressFamily::Inet6))
     }
 }
 
 impl AddrOutput {
+    /// Iterate IPv4 address entries.
     pub fn ipv4_addrs(&self) -> impl Iterator<Item = &AddrInfo> {
         self.addr_info.iter().filter(|info| info.is_ipv4())
     }
 
+    /// Iterate IPv6 address entries.
     pub fn ipv6_addrs(&self) -> impl Iterator<Item = &AddrInfo> {
         self.addr_info.iter().filter(|info| info.is_ipv6())
     }
 }
 
+/// Fetch address data using the default backend.
 pub async fn get(dev: Option<&str>) -> anyhow::Result<Vec<AddrOutput>> {
     get_with_backend(Backend::Json, dev).await
 }
 
+/// Fetch address data using an explicit backend.
 pub async fn get_with_backend(
     backend: Backend,
     dev: Option<&str>,

ipjs/src/subcommands/link/mod.rs

@@ -11,6 +11,7 @@ use macaddr::MacAddr;
 use rtnetlink::packet_route::link::State as NetlinkOperState;
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
+/// One interface row from `ip -j link show`.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct LinkOutput {
     pub ifindex: u32,
@@ -21,6 +22,7 @@ pub struct LinkOutput {
     pub address: Option<MacAddr>,
 }
 
+/// Operational state of a Linux network interface.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum OperState {
     Up,
@@ -100,10 +102,12 @@ impl From<NetlinkOperState> for OperState {
     }
 }
 
+/// Fetch link rows using the default backend.
 pub async fn get(dev: Option<&str>) -> anyhow::Result<Vec<LinkOutput>> {
     get_with_backend(Backend::Json, dev).await
 }
 
+/// Fetch link rows using an explicit backend.
 pub async fn get_with_backend(
     backend: Backend,
     dev: Option<&str>,

ipjs/src/subcommands/neighbor/mod.rs

@@ -1,8 +1,4 @@
-//! ```bash
-//! ip -j n s
-//! ```
-//!
-//! yes. this is a real call.
+//! Typed wrappers for `ip -j neigh show`.
 
 pub mod json;
 #[cfg(all(unix, feature = "experimental-nl"))]
@@ -16,18 +12,18 @@ use macaddr::MacAddr;
 use serde::{Deserialize, Serialize};
 use strum::{Display, EnumString};
 
+/// Structured neighbor query input matching the common `ip neigh` flags.
 #[derive(Debug, PartialEq, Eq, Clone, Hash, Serialize, Deserialize)]
 pub struct NeighborInput {
-    /// supports only the last item (ignore), `to` keyword is optional
+    /// Destination address filter. The optional `to` keyword in CLI form is implicit here.
     pub to: Option<IpAddr>,
-    /// supports only one item (it complains if multiple)
-    pub dev: Option<String>, // im all for simplicity
-    /// takes multiple, has to have `nud` before bro or it will think you `to`
+    /// Interface-name filter.
+    pub dev: Option<String>,
+    /// Neighbor-state filters.
     pub nud: Vec<NUDState>,
 }
 
-// as input this must be lowercase. as output it is uppercase
-/// docs for items come from a random ahh man website idk
+/// Linux neighbor reachability states.
 #[derive(
     Debug, PartialEq, Eq, EnumString, Display, Clone, Copy, Hash, Serialize, Deserialize, Default,
 )]
@@ -70,7 +66,7 @@ pub enum NUDState {
     Other(u16),
 }
 
-/// everything i see
+/// One neighbor row from `ip -j neigh show`.
 #[derive(Debug, PartialEq, Eq, Clone, Hash, Serialize, Deserialize)]
 pub struct NeighborItem {
     #[serde(rename(deserialize = "dst"))]
@@ -83,6 +79,7 @@ pub struct NeighborItem {
     pub state: Vec<NUDState>,
 }
 
+/// Fetch neighbor rows using the default backend.
 pub async fn get(
     ip: Option<IpAddr>,
     dev: Option<&str>,
@@ -91,6 +88,7 @@ pub async fn get(
     get_with_backend(Backend::Json, ip, dev, nud).await
 }
 
+/// Fetch neighbor rows using an explicit backend.
 pub async fn get_with_backend(
     backend: Backend,
     ip: Option<IpAddr>,