add documentation

4 files changed, 46 insertions, 0 deletions

diff --git a/src/addr.rs b/src/addr.rs
index ed68fcc..2c949f7 100644
--- a/src/addr.rs
+++ b/src/addr.rs
@@ -5,6 +5,7 @@ use std::net::IpAddr;
 use futures::{future, TryStreamExt};
 use netlink_packet_route::{AddressMessage, AF_INET, AF_INET6, RT_SCOPE_LINK, RT_SCOPE_UNIVERSE};
 
+/// Flushes all addresses of an interface.
 pub async fn flush(link: String) -> Result<()> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
     tokio::spawn(conn);
@@ -35,6 +36,7 @@ pub async fn flush(link: String) -> Result<()> {
     Ok(())
 }
 
+/// Flushes the IPv4 addresses of an interface.
 pub async fn flush4(link: String) -> Result<()> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
     tokio::spawn(conn);
@@ -66,6 +68,7 @@ pub async fn flush4(link: String) -> Result<()> {
     Ok(())
 }
 
+/// Flushes the IPv6 addresses of an interface.
 pub async fn flush6(link: String) -> Result<()> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
     tokio::spawn(conn);
@@ -97,6 +100,7 @@ pub async fn flush6(link: String) -> Result<()> {
     Ok(())
 }
 
+/// Flushes all global unicast IPv6 addresses from all interfaces.
 pub async fn flush6_global() -> Result<()> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
     tokio::spawn(conn);
@@ -120,6 +124,7 @@ pub async fn flush6_global() -> Result<()> {
     Ok(())
 }
 
+/// Adds an IP address to an interface.
 pub async fn add(link: String, addr: IpAddr, prefix_len: u8) -> Result<()> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
     tokio::spawn(conn);
@@ -140,6 +145,8 @@ pub async fn add(link: String, addr: IpAddr, prefix_len: u8) -> Result<()> {
     Ok(())
 }
 
+/// Adds a link-scope IP address to an interface.
+/// This is especially useful with IPv6.
 pub async fn add_link_local(link: String, addr: IpAddr, prefix_len: u8) -> Result<()> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
     tokio::spawn(conn);
diff --git a/src/link.rs b/src/link.rs
index a881527..058eb37 100644
--- a/src/link.rs
+++ b/src/link.rs
@@ -14,6 +14,7 @@ pub enum LinkState {
     Down,
 }
 
+/// Brings an interface up or down.
 #[cfg(feature = "link")]
 pub async fn set(link: String, state: LinkState) -> Result<()> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
@@ -40,6 +41,12 @@ pub async fn set(link: String, state: LinkState) -> Result<()> {
     Ok(())
 }
 
+/// Reports whether an interface is up.
+///
+/// # Errors
+///
+/// This function fails if the interface doesn't exist
+/// or if any other `rtnetlink` error occurs.
 pub async fn is_up(link: String) -> Result<bool> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
     tokio::spawn(conn);
@@ -57,6 +64,7 @@ pub async fn is_up(link: String) -> Result<bool> {
     Ok(is_up)
 }
 
+/// Sets the MTU of an interface.
 #[cfg(feature = "link")]
 pub async fn set_mtu(link: String, mtu: u32) -> Result<()> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
@@ -77,6 +85,13 @@ pub async fn set_mtu(link: String, mtu: u32) -> Result<()> {
     Ok(())
 }
 
+/// Creates a VLAN interface on top of a parent interface.
+///
+/// # Arguments
+///
+/// * `link` - The name of the VLAN interface to be created.
+/// * `parent` - The name of the parent interface for the actual traffic.
+/// * `vlan_id` - The VLAN ID for tagging.
 #[cfg(feature = "link")]
 pub async fn add_vlan(link: String, parent: String, vlan_id: u16) -> Result<()> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
@@ -103,6 +118,7 @@ pub async fn add_vlan(link: String, parent: String, vlan_id: u16) -> Result<()>
     Ok(())
 }
 
+/// Waits for an interface to come up, including waiting for its creation.
 pub async fn wait_up(link: String) -> Result<()> {
     while !exists(link.clone()).await? || !is_up(link.clone()).await? {
         sleep(Duration::from_millis(200)).await;
@@ -111,6 +127,7 @@ pub async fn wait_up(link: String) -> Result<()> {
     Ok(())
 }
 
+/// Reports whether an interface exists.
 pub async fn exists(link: String) -> Result<bool> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
     tokio::spawn(conn);
@@ -127,6 +144,7 @@ pub async fn exists(link: String) -> Result<bool> {
     Ok(exists)
 }
 
+/// Waits until an interface is created.
 pub async fn wait_exists(link: String) -> Result<()> {
     while !exists(link.clone()).await? {
         sleep(Duration::from_millis(200)).await;
diff --git a/src/route.rs b/src/route.rs
index cd5e032..398cd3e 100644
--- a/src/route.rs
+++ b/src/route.rs
@@ -6,6 +6,7 @@ use futures::{future, TryStreamExt};
 use netlink_packet_route::{RouteMessage, RT_SCOPE_LINK};
 use rtnetlink::IpVersion;
 
+/// Flushes all IPv4 routes from an interface.
 pub async fn flush4(link: String) -> Result<()> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
     tokio::spawn(conn);
@@ -42,6 +43,7 @@ pub async fn flush4(link: String) -> Result<()> {
     Ok(())
 }
 
+/// Flushes all IPv6 routes from an interface.
 pub async fn flush6(link: String) -> Result<()> {
     let (conn, handle, _) = rtnetlink::new_connection()?;
     tokio::spawn(conn);
@@ -78,6 +80,7 @@ pub async fn flush6(link: String) -> Result<()> {
     Ok(())
 }
 
+/// Adds a simple IPv4 route with an optional gateway.
 pub async fn add4(
     dst: Ipv4Addr,
     prefix_len: u8,
@@ -115,6 +118,7 @@ pub async fn add4(
     Ok(())
 }
 
+/// Adds a simple IPv6 route with an optional gateway.
 pub async fn add6(
     dst: Ipv6Addr,
     prefix_len: u8,
diff --git a/src/tunnel.rs b/src/tunnel.rs
index cfab916..df172c0 100644
--- a/src/tunnel.rs
+++ b/src/tunnel.rs
@@ -20,6 +20,15 @@ impl Drop for Sit {
 }
 
 impl Sit {
+    /// Creates a new 6in4 tunnel on a parent device.
+    ///
+    /// # Arguments
+    ///
+    /// * `name` - The name of the tunnel to be created.
+    /// * `master` - The name of the parent interface for actual traffic.
+    /// * `laddr` - The address of the local tunnel endpoint,
+    ///             e.g. the WAN IPv4 address of a router.
+    /// * `raddr` - The address of the remote tunnel endpoint, e.g. a tunnel server.
     pub fn new(name: String, master: String, laddr: Ipv4Addr, raddr: Ipv4Addr) -> Result<Self> {
         let tnlname = CString::new(&*name)?;
         let ifmaster = CString::new(&*master)?;
@@ -108,6 +117,14 @@ impl Drop for IpIp6 {
 }
 
 impl IpIp6 {
+    /// Creates a new 4in6 tunnel on a parent device.
+    ///
+    /// # Arguments
+    ///
+    /// * `name` - The name of the tunnel to be created.
+    /// * `master` - The name of the parent interface for actual traffic.
+    /// * `laddr` - The address of the local tunnel endpoint, e.g. the IPv6 GUA of a DS-Lite B4.
+    /// * `raddr` - The address of the remote tunnel endpoint, e.g. a DS-Lite AFTR.
     pub fn new(name: String, master: String, laddr: Ipv6Addr, raddr: Ipv6Addr) -> Result<Self> {
         let tnlname = CString::new(&*name)?;
         let ifmaster = CString::new(&*master)?;