docs(wireguard-broker): add docs and examples

wireguard-broker/src/brokers/netlink.rs

@@ -1,4 +1,31 @@
 #![cfg(target_os = "linux")]
+//! Linux-specific WireGuard PSK broker implementation using netlink.
+//!
+//! This module provides direct kernel communication through netlink sockets for managing
+//! WireGuard pre-shared keys. It's more efficient than the command-line implementation
+//! but only available on Linux systems.
+//!
+//! # Examples
+//!
+//! ```no_run
+//! use rosenpass_secret_memory::{Public, Secret};
+//! use rosenpass_wireguard_broker::{WireGuardBroker, SerializedBrokerConfig, WG_KEY_LEN, WG_PEER_LEN};
+//! use rosenpass_wireguard_broker::brokers::netlink::NetlinkWireGuardBroker;
+//!
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! let mut broker = NetlinkWireGuardBroker::new()?;
+//!
+//! let config = SerializedBrokerConfig {
+//!     interface: "wg0".as_bytes(),
+//!     peer_id: &Public::zero(), // Replace with actual peer ID
+//!     psk: &Secret::zero(),     // Replace with actual PSK
+//!     additional_params: &[],
+//! };
+//!
+//! broker.set_psk(config)?;
+//! # Ok(())
+//! # }
+//! ```
 
 use std::fmt::Debug;
 
@@ -8,12 +35,14 @@ use crate::api::config::NetworkBrokerConfig;
 use crate::api::msgs;
 use crate::{SerializedBrokerConfig, WireGuardBroker};
 
+/// Error that can occur when connecting to the WireGuard netlink interface.
 #[derive(thiserror::Error, Debug)]
 pub enum ConnectError {
     #[error(transparent)]
     ConnectError(#[from] wg::err::ConnectError),
 }
 
+/// Errors that can occur during netlink operations.
 #[derive(thiserror::Error, Debug)]
 pub enum NetlinkError {
     #[error(transparent)]
@@ -22,6 +51,7 @@ pub enum NetlinkError {
     GetDevice(#[from] wg::err::GetDeviceError),
 }
 
+/// Errors that can occur when setting a pre-shared key.
 #[derive(thiserror::Error, Debug)]
 pub enum SetPskError {
     #[error("The indicated wireguard interface does not exist")]
@@ -55,11 +85,33 @@ impl From<SetPskNetlinkError> for SetPskMsgsError {
     }
 }
 
+/// WireGuard broker implementation using Linux netlink sockets.
+///
+/// This implementation communicates directly with the kernel through netlink sockets,
+/// providing better performance than command-line based implementations.
+///
+/// # Examples
+///
+/// ```no_run
+/// use rosenpass_wireguard_broker::brokers::netlink::NetlinkWireGuardBroker;
+/// use rosenpass_wireguard_broker::WireGuardBroker;
+/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+/// let mut broker = NetlinkWireGuardBroker::new()?;
+/// # Ok(())
+/// # }
+/// ```
+///
+/// # Platform Support
+///
+/// This implementation is only available on Linux systems and requires appropriate
+/// permissions to use netlink sockets.
 pub struct NetlinkWireGuardBroker {
     sock: wg::WgSocket,
 }
 
 impl NetlinkWireGuardBroker {
+    /// Opens a netlink socket to the WireGuard kernel module
+    /// and returns a new netlink-based WireGuard broker.
     pub fn new() -> Result<Self, ConnectError> {
         let sock = wg::WgSocket::connect()?;
         Ok(Self { sock })