Documentation updates

src/descriptors.rs

@@ -277,7 +277,9 @@ descriptor_fields! {
 
         /// `bConfigurationValue` descriptor field: Identifier for the configuration.
         ///
-        /// Pass this to `Device::set_configuration` to select this configuration.
+        /// Pass this value to
+        /// [`Device::set_configuration`][crate::Device::set_configuration] to
+        /// select this configuration.
         #[doc(alias = "bConfigurationValue")]
         pub fn configuration_value at 5 -> u8;
 
@@ -361,7 +363,8 @@ impl<'a> InterfaceGroup<'a> {
 pub struct InterfaceAltSetting<'a>(&'a [u8]);
 
 impl<'a> InterfaceAltSetting<'a> {
-    /// Get the interface descriptor followed by all trailing endpoint and other descriptors.
+    /// Get the interface descriptor followed by all trailing endpoint and other
+    /// descriptors up to the next interface descriptor.
     pub fn descriptors(&self) -> Descriptors {
         Descriptors(self.0)
     }
@@ -478,7 +481,7 @@ descriptor_fields! {
 
         /// Get the raw value of the `bmAttributes` descriptor field.
         ///
-        /// See [transfer_type][Self::transfer_type] for the transfer type field.
+        /// See [`transfer_type``][Self::transfer_type] for the transfer type field.
         #[doc(alias = "bmAttributes")]
         pub fn attributes at 3 -> u8;
 

src/device.rs

@@ -53,6 +53,10 @@ impl Device {
     }
 
     /// Get information about the active configuration.
+    ///
+    /// This returns cached data and does not perform IO. However, it can fail if the
+    /// device is unconfigured, or if it can't find a configuration descriptor for
+    /// the configuration reported as active by the OS.
     pub fn active_configuration(&self) -> Result<Configuration, ActiveConfigurationError> {
         let active = self.backend.active_configuration_value();
 
@@ -63,7 +67,9 @@ impl Device {
             })
     }
 
-    /// Iterate over all configurations of the device.
+    /// Get an iterator returning information about each configuration of the device.
+    ///
+    /// This returns cached data and does not perform IO.
     pub fn configurations(&self) -> impl Iterator<Item = Configuration> {
         self.backend
             .configuration_descriptors()
@@ -190,7 +196,7 @@ impl Device {
         self.backend.reset()
     }
 
-    /// Synchronously submit a single **IN (device-to-host)** transfer on the default **control** endpoint.
+    /// Synchronously perform a single **IN (device-to-host)** transfer on the default **control** endpoint.
     ///
     /// ### Platform-specific notes
     ///
@@ -208,7 +214,7 @@ impl Device {
         self.backend.control_in_blocking(control, data, timeout)
     }
 
-    /// Synchronously submit a single **OUT (host-to-device)** transfer on the default **control** endpoint.
+    /// Synchronously perform a single **OUT (host-to-device)** transfer on the default **control** endpoint.
     ///
     /// ### Platform-specific notes
     ///
@@ -326,7 +332,7 @@ impl Interface {
         self.backend.set_alt_setting(alt_setting)
     }
 
-    /// Synchronously submit a single **IN (device-to-host)** transfer on the default **control** endpoint.
+    /// Synchronously perform a single **IN (device-to-host)** transfer on the default **control** endpoint.
     ///
     /// ### Platform-specific notes
     ///
@@ -341,7 +347,7 @@ impl Interface {
         self.backend.control_in_blocking(control, data, timeout)
     }
 
-    /// Synchronously submit a single **OUT (host-to-device)** transfer on the default **control** endpoint.
+    /// Synchronously perform a single **OUT (host-to-device)** transfer on the default **control** endpoint.
     ///
     /// ### Platform-specific notes
     ///

src/enumeration.rs

@@ -15,6 +15,7 @@ use crate::{Device, Error};
 /// * Some fields are platform-specific
 ///     * Linux: `path`
 ///     * Windows: `instance_id`, `parent_instance_id`, `port_number`, `driver`
+///     * macOS: `registry_id`, `location_id`
 #[derive(Clone)]
 pub struct DeviceInfo {
     #[cfg(target_os = "linux")]
@@ -157,12 +158,20 @@ impl DeviceInfo {
     }
 
     /// Manufacturer string, if available without device IO
+    ///
+    /// ### Platform-specific notes
+    ///  * Windows: this comes from the driver, and for some drivers
+    ///    does not match the string returned from the device.
     #[doc(alias = "iManufacturer")]
     pub fn manufacturer_string(&self) -> Option<&str> {
         self.manufacturer_string.as_deref()
     }
 
     /// Product string, if available without device IO
+    ///
+    /// ### Platform-specific notes
+    ///  * Windows: this comes from the driver, and for some drivers
+    ///    does not match the string returned from the device.
     #[doc(alias = "iProduct")]
     pub fn product_string(&self) -> Option<&str> {
         self.product_string.as_deref()

src/lib.rs

@@ -3,10 +3,12 @@
 //!
 //! `nusb` is comparable to the C library [libusb] and its Rust bindings [rusb],
 //! but written in pure Rust. It's built on and exposes async APIs by default,
-//! but can be made blocking using [`futures_lite::future::block_on`].
+//! but can be made blocking using [`futures_lite::future::block_on`][block_on]
+//! or similar.
 //!
 //! [libusb]: https://libusb.info
 //! [rusb]: https://docs.rs/rusb/
+//! [block_on]: https://docs.rs/futures-lite/latest/futures_lite/future/fn.block_on.html
 //!
 //! Use `nusb` to write user-space drivers in Rust for non-standard USB devices
 //! or those without kernel support. For devices implementing a standard USB
@@ -26,6 +28,8 @@
 //! device.
 //!
 //! Call [`device_info.open()`](`DeviceInfo::open`) to open a selected device.
+//! Additional information about the device can be queried with
+//! [`device.active_configuration()`](`Device::active_configuration`).
 //!
 //! USB devices consist of one or more interfaces exposing a group of
 //! functionality. A device with multiple interfaces is known as a composite
@@ -105,7 +109,10 @@
 //!
 //! ### macOS
 //!
-//! Not yet supported.
+//! `nusb` uses IOKit on macOS.
+//!
+//! Users have access to USB devices by default, with no permission configuration needed.
+//! Devices with a kernel driver are not accessible.
 
 use std::io;
 

src/platform/macos_iokit/transfer.rs

@@ -57,7 +57,7 @@ impl Drop for TransferData {
 /// Bring the data accessed on the transfer callback out-of-line
 /// so that we can have a reference to it while the callback may
 /// write to other fields concurrently. This could be included
-/// in TransferData with the proposed [UnsafePinned](https://github.com/rust-lang/rfcs/pull/3467)
+/// in `TransferData`` with the proposed [`UnsafePinned`](https://github.com/rust-lang/rfcs/pull/3467)
 pub struct TransferDataInner {
     actual_len: usize,
     callback_data: *mut c_void,

src/transfer/buffer.rs

@@ -75,7 +75,7 @@ impl TransferRequest for RequestBuffer {
 /// you how many bytes were successfully sent, which may be useful in the case
 /// of a partially-completed transfer.
 ///
-/// The `ResponseBuffer` can be turned into an empty Vec to re-use the allocation
+/// The `ResponseBuffer` can be turned into an empty `Vec` to re-use the allocation
 /// for another transfer, or dropped to free the memory.
 pub struct ResponseBuffer {
     pub(crate) buf: *mut u8,