fix #12 basic lib example; lib.rs doc example

Cargo.toml

@@ -5,7 +5,7 @@ description = "List system USB buses and devices; a modern cross-platform `lsusb
 repository = "https://github.com/tuna-f1sh/cyme"
 readme = "README.md"
 license = "GPL-3.0-or-later"
-version = "1.5.0"
+version = "1.5.1"
 edition = "2021"
 keywords = ["usb", "lsusb", "system_profiler", "macos", "libusb"]
 categories = ["command-line-utilities"]

examples/print_devices.rs

@@ -0,0 +1,27 @@
+use cyme::lsusb::profiler;
+use cyme::display;
+
+fn main() -> Result<(), String> {
+    // get all system devices - use get_spusb_with_extra for verbose info
+    let sp_usb = profiler::get_spusb(false).map_err(|e| {
+        format!("Failed to gather system USB data from libusb, Error({})", e)
+    })?;
+
+    // flatten since we don't care tree/buses
+    let devices = sp_usb.flatten_devices();
+
+    // print with default [`display::PrintSettings`]
+    display::print_flattened_devices(&devices, &display::PrintSettings::default());
+
+    // alternatively interate over devices and do something with them
+    for device in devices {
+        match (device.vendor_id, device.product_id) {
+            (Some(0x05ac), Some(_)) => {
+                println!("Found Apple device: {}", device);
+            }
+            _ => {}
+        }
+    }
+
+    Ok(())
+}

src/config.rs

@@ -60,7 +60,7 @@ pub struct Config {
     pub ascii: bool,
     // /// Output charactor encoding
     // pub encoding: display::Encoding,
-    /// Disables all [`Display::Block`] icons
+    /// Disables all [`display::Block`] icons
     pub no_icons: bool,
     /// Show block headings
     pub headings: bool,

src/error.rs

@@ -24,7 +24,7 @@ pub enum ErrorKind {
     Config,
     /// [`std::io::Error`] probably not found when reading file to parse
     Io,
-    /// [`libusb::Error`] error
+    /// [`rusb::Error`] error
     LibUSB,
     /// Error calling udev
     Udev,

src/lib.rs

@@ -1,5 +1,36 @@
 //! List system USB buses and devices; a modern `lsusb` that attempts to maintain compatibility with, but also add new features.
 //! Includes a macOS `system_profiler` parser module and `lsusb` for non-macOS systems/gathering more verbose information.
+//!
+//! # Examples
+//!
+//! To get all the USB devices on cross-platform systems using libusb:
+//!
+//! ```ignore
+//! use cyme::lsusb::profiler;
+//! let sp_usb = profiler::get_spusb(false).unwrap();
+//! ```
+//!
+//! It's often useful to then flatten this into a list of devices ([`system_profiler::USBDevice`]):
+//!
+//! ```ignore
+//! // flatten since we don't care tree/buses
+//! let devices = sp_usb.flatten_devices();
+//!
+//! for device in devices {
+//!    format!("{}");
+//! }
+//! ```
+//!
+//! One can then print with the cyme display module:
+//!
+//! ```ignore
+//! use cyme::display;
+//! // print with default [`display::PrintSettings`]
+//! display::print_flattened_devices(&devices, &display::PrintSettings::default());
+//! ```
+//!
+//! The [`system_profiler::SPUSBDataType`] struct contains system [`system_profiler::USBBus`]s, which contain [`system_profiler::USBDevice`]s as a USB tree.
+//!
 #![allow(dead_code)]
 #![warn(missing_docs)]
 use simple_logger::SimpleLogger;

src/lsusb.rs

@@ -603,7 +603,7 @@ pub mod profiler {
         // merge if passed has any buses
         if !spusb.buses.is_empty() {
             for mut bus in libusb_spusb.buses {
-                if let Some(mut existing) = spusb
+                if let Some(existing) = spusb
                     .buses
                     .iter_mut()
                     .find(|b| b.get_bus_number() == bus.get_bus_number())