Add documentation and tests.

1 files changed, 75 insertions, 11 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 742e02c..7a9fb01 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,20 +1,38 @@
-//! Traits for a hardware-agnostic USB host interface.
+//! This crate defines a set of traits for use on the host side of the
+//! USB.
+//!
+//! The `USBHost` defines the Host Controller Interface that can be
+//! used by the `Driver` interface.
+//!
+//! The `Driver` interface defines the set of functions necessary to
+//! use devices plugged into the host.
 
 #![no_std]
 
-mod descriptor;
-mod setup;
+pub mod descriptor;
+pub mod setup;
 
 pub use descriptor::*;
 pub use setup::*;
 
+/// Errors that can be generated when attempting to do a USB transfer.
 #[derive(Debug)]
 pub enum TransferError {
+    /// An error that may be retried.
     Retry(&'static str),
+
+    /// A permanent error.
     Permanent(&'static str),
 }
 
+/// Trait for host controller interface.
 pub trait USBHost {
+    /// Issue a control transfer with an optional data stage to
+    /// `ep`. The data stage direction is determined by the direction
+    /// of `bm_request_type`.
+    ///
+    /// On success, the amount of data transferred into `buf` is
+    /// returned.
     fn control_transfer(
         &mut self,
         ep: &mut dyn Endpoint,
@@ -25,16 +43,26 @@ pub trait USBHost {
         buf: Option<&mut [u8]>,
     ) -> Result<usize, TransferError>;
 
+    /// Issue a transfer from `ep` to the host.
+    ///
+    /// On success, the amount of data transferred into `buf` is
+    /// returned.
     fn in_transfer(
         &mut self,
         ep: &mut dyn Endpoint,
         buf: &mut [u8],
     ) -> Result<usize, TransferError>;
 
+    /// Issue a transfer from the host to `ep`.
+    ///
+    /// On success, the amount of data transferred from `buf` is
+    /// returned. This should always be equal to `buf.len()`.
     fn out_transfer(&mut self, ep: &mut dyn Endpoint, buf: &[u8]) -> Result<usize, TransferError>;
 }
 
-// cf §9.6.6 of USB 2.0
+/// The type of transfer to use when talking to USB devices.
+///
+/// cf §9.6.6 of USB 2.0
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub enum TransferType {
     Control = 0,
@@ -43,50 +71,86 @@ pub enum TransferType {
     Interrupt = 3,
 }
 
-// ibid
+/// The direction of the transfer with the USB device.
+///
+/// cf §9.6.6 of USB 2.0
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub enum Direction {
     Out,
     In,
 }
 
+/// `Endpoint` defines the USB endpoint for various transfers.
 pub trait Endpoint {
+    /// Address of the device owning this endpoint. Must be between 0
+    /// and 127.
     fn address(&self) -> u8;
 
+    /// Endpoint number, irrespective of direction. (e.g., for both
+    /// endpoint addresses, `0x81` and `0x01`, this function would
+    /// return `0x01`).
     fn endpoint_num(&self) -> u8;
 
+    /// The type of transfer this endpoint uses.
     fn transfer_type(&self) -> TransferType;
 
+    /// The direction of transfer this endpoint accepts.
     fn direction(&self) -> Direction;
 
+    /// The maximum packet size for this endpoint.
     fn max_packet_size(&self) -> u16;
 
+    /// The data toggle sequence bit for the next transfer from the
+    /// device to the host.
     fn in_toggle(&self) -> bool;
 
+    /// The `USBHost` will, when required, update the data toggle
+    /// sequence bit for the next device to host transfer.
     fn set_in_toggle(&mut self, toggle: bool);
 
+    /// The data toggle sequence bit for the next transfer from the
+    /// host to the device.
     fn out_toggle(&self) -> bool;
 
+    /// The `USBHost` will, when required, update the data toggle
+    /// sequence bit for the next host to device transfer.
     fn set_out_toggle(&mut self, toggle: bool);
 }
 
+/// Types of errors that can be returned from a `Driver`.
 #[derive(Copy, Clone, Debug)]
 pub enum DriverError {
+    /// An error that may be retried.
     Retry(u8, &'static str),
+
+    /// A permanent error.
     Permanent(u8, &'static str),
 }
+
+/// Trait for drivers on the USB host.
 pub trait Driver: core::fmt::Debug {
+    /// Does this driver want `device`?
+    ///
+    /// Answering `true` to this not necessarily mean the driver will
+    /// get `device`.
     fn want_device(&self, device: &DeviceDescriptor) -> bool;
 
+    /// Add `device` with address `address` to the driver's registry,
+    /// if necessary.
     fn add_device(&mut self, device: DeviceDescriptor, address: u8) -> Result<(), DriverError>;
 
+    /// Remove the device at address `address` from the driver's
+    /// registry, if necessary.
     fn remove_device(&mut self, address: u8);
 
+    /// Called regularly by the USB host to allow the driver to do any
+    /// work necessary on its registered devices.
+    ///
+    /// `millis` is the current time, in milliseconds from some
+    /// arbitrary starting point. It should be expected that after a
+    /// long enough run-time, this value will wrap.
+    ///
+    /// `usbhost` may be used for communication with the USB when
+    /// required.
     fn tick(&mut self, millis: usize, usbhost: &mut dyn USBHost) -> Result<(), DriverError>;
 }
-
-// TODO: There needs to be a per-interface/function driver trait, as
-// well, since that's how most drivers will actually work.
-//
-// As a result, the host driver has to at least get the full
-// configuration.