Add top-level docs and update README

diff --git a/README.md b/README.md
index 93686b81999fcc57db70f5000c498e026f56d88d..53904693600e874e1ed5fff823d2653cfa5b0603 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,2 +1,56 @@
 # netwatcher
-Query network interfaces and watch for changes in Rust
+
+![Crates.io Version](https://img.shields.io/crates/v/netwatcher)
+![docs.rs](https://img.shields.io/docsrs/netwatcher)
+
+`netwatcher` is a cross-platform Rust library for enumerating network interfaces and their IP addresses, featuring the ability to watch for changes to those interfaces _efficiently_. It uses platform-specific methods to detect when interface changes have occurred instead of polling, which means that you find out about changes more quickly and there is no CPU or wakeup overhead when nothing is happening.
+
+## Current platform suport
+
+| Platform | Min Version | List | Watch | Notes                                                                                 |
+|----------|-------------|------|-------|---------------------------------------------------------------------------------------|
+| Windows  | -           | ✅    | ✅     |                                                                                       |
+| Mac      | 10.14       | ✅    | ✅     |                                                                                       |
+| Linux    | -           | ✅    | ✅     | Creates a background thread                                                           |
+| iOS      | 12.0        | ✅    | ✅     |                                                                                       |
+| Android  | -           | ✅    | ❌     | Linux-style watch fails on Android 11+ due to privacy restrictions. Alternatives WIP. |
+
+## Usage
+
+### Listing interfaces
+
+```rust
+/// Returns a HashMap from ifindex (a `u32`) to an `Interface` struct
+let interfaces = netwatcher::list_interfaces().unwrap();
+for i in interfaces.values() {
+    println!("interface {} has {} IPs", i.name, i.ips.len());
+}
+```
+
+### Watching for changes to interfaces
+
+```rust
+let handle = netwatcher::watch_interfaces(|update| {
+    // This callback will fire once immediately with the existing state
+
+    // Update includes the latest snapshot of all interfaces
+    println!("Current interface map: {:#?}", update.interfaces);
+
+    // The `UpdateDiff` describes changes since previous callback
+    // You can choose whether to use the snapshot, diff, or both
+    println!("ifindexes added: {:?}", update.diff.added);
+    println!("ifindexes removed: {:?}", update.diff.removed);
+    for (ifindex, if_diff) in update.diff.modified {
+        println!("Interface index {} has changed", ifindex);
+        println!("Added IPs: {:?}", if_diff.addrs_added);
+        println!("Removed IPs: {:?}", if_diff.addrs_removed);
+    }
+});
+// keep `handle` alive as long as you want callbacks
+// ...
+drop(handle);
+```
+
+## Licence
+
+Apache License Version 2.0 - see `LICENSE`.
\ No newline at end of file

diff --git a/examples/watch.rs b/examples/watch.rs
index 2f9539cfbb0b8dfdd075e1ebf4c1941f19558712..767fd19ee72d7fe1fa2e848f722c1579ca8b0112 100644 (file)
--- a/examples/watch.rs
+++ b/examples/watch.rs
@@ -5,8 +5,8 @@ fn main() {
 
     let handle = netwatcher::watch_interfaces(|update| {
         println!("Interface update!");
-        println!("State: {:?}", update.interfaces);
-        println!("Diff: {:?}", update.diff);
+        println!("State: {:#?}", update.interfaces);
+        println!("Diff: {:#?}", update.diff);
     });
 
     std::thread::sleep(Duration::from_secs(30));

diff --git a/src/lib.rs b/src/lib.rs
index 495b9e64f5098aadb9b1d7d8b8d7f4a4603f2a40..dfc4395cfda75ad9bf7a81f33d887edc96c4a390 100644 (file)
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,45 @@
+//! # netwatcher
+//!
+//! `netwatcher` is a cross-platform library for enumerating network interfaces and their
+//! IP addresses, featuring the ability to watch for changes to those interfaces
+//! _efficiently_. It uses platform-specific methods to detect when interface changes
+//! have occurred instead of polling, which means that you find out about changes more
+//! quickly and there is no CPU or wakeup overhead when nothing is happening.
+//! 
+//! ## List example
+//! 
+//! ```
+//! /// Returns a HashMap from ifindex (a `u32`) to an `Interface` struct
+//! let interfaces = netwatcher::list_interfaces().unwrap();
+//! for i in interfaces.values() {
+//!     println!("interface {} has {} IPs", i.name, i.ips.len());
+//! }
+//! ```
+//! 
+//! ## Watch example
+//! 
+//! ```
+//! let handle = netwatcher::watch_interfaces(|update| {
+//!     // This callback will fire once immediately with the existing state
+//! 
+//!     // Update includes the latest snapshot of all interfaces
+//!     println!("Current interface map: {:#?}", update.interfaces);
+//! 
+//!     // The `UpdateDiff` describes changes since previous callback
+//!     // You can choose whether to use the snapshot, diff, or both
+//!     println!("ifindexes added: {:?}", update.diff.added);
+//!     println!("ifindexes removed: {:?}", update.diff.removed);
+//!     for (ifindex, if_diff) in update.diff.modified {
+//!         println!("Interface index {} has changed", ifindex);
+//!         println!("Added IPs: {:?}", if_diff.addrs_added);
+//!         println!("Removed IPs: {:?}", if_diff.addrs_removed);
+//!     }
+//! });
+//! // keep `handle` alive as long as you want callbacks
+//! // ...
+//! drop(handle);
+//! ```
+
 use std::{
     collections::{HashMap, HashSet},
     net::{IpAddr, Ipv4Addr, Ipv6Addr},