a more applied doc list_buses example

src/lib.rs

@@ -153,7 +153,9 @@ pub fn list_devices() -> Result<impl Iterator<Item = DeviceInfo>, Error> {
 
 /// Get an iterator listing the system USB buses.
 ///
-/// ### Example
+/// ### Examples
+///
+/// Filter for a specific bus ID:
 ///
 /// ```no_run
 /// use nusb;
@@ -162,6 +164,20 @@ pub fn list_devices() -> Result<impl Iterator<Item = DeviceInfo>, Error> {
 ///    .expect("bus #1 not found");
 /// ```
 ///
+/// Group devices by bus:
+///
+/// ```no_run
+/// use std::collections::HashMap;
+///
+/// let devices = nusb::list_devices().unwrap().collect::<Vec<_>>();
+/// let buses: HashMap<String, (nusb::BusInfo, Vec::<nusb::DeviceInfo>)> = nusb::list_buses().unwrap()
+///     .map(|bus| {
+///         let bus_id = bus.bus_id().to_owned();
+///         (bus.bus_id().to_owned(), (bus, devices.clone().into_iter().filter(|dev| dev.bus_id() == bus_id).collect()))
+///     })
+///     .collect();
+/// ```
+///
 /// ### Platform-specific notes
 /// * On Linux, the abstraction of the "bus" is a phony device known as the root hub. This device is available at bus.root_hub()
 pub fn list_buses() -> Result<impl Iterator<Item = BusInfo>, Error> {